hex-audit 0.5.1 → 0.5.2

package/dist/core/notes.js

@@ -0,0 +1,160 @@
+/**
+ * Canonical notes-mutation logic for Diane — the voice-narration audit
+ * companion. Shared by the `hex note` CLI command, the `/diane` skill (which
+ * shells `hex note ...`), and the dashboard's Notes API routes.
+ *
+ * Notes live under `<output_dir>/notes/`:
+ *   notes.json              index: active contract, contract list, sessions
+ *   general.md              cross-cutting / protocol-wide notes
+ *   contracts/<Name>.md     one Obsidian-style doc per contract
+ *   sessions/<ts>.md        raw transcripts (audit trail; never auto-deleted)
+ *   audio/<ts>.webm         raw recordings (kept until transcribed)
+ *
+ * Like src/core/issues.ts, this module depends ONLY on node:fs / node:path and
+ * is parameterized by `outputDir`, so the dashboard can import it across the
+ * src/ <-> dashboard/ boundary via `experimental.externalDir` without dragging
+ * CLI deps (chalk/ora/zod) into the Next.js bundle. Keep it that way.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const EMPTY_INDEX = { active_contract: null, contracts: [], sessions: [] };
+// ─── Paths ──────────────────────────────────────────────────────────
+function notesDir(outputDir) {
+    return path.join(outputDir, 'notes');
+}
+/** Filesystem-safe doc filename from a contract display name. */
+function safeName(name) {
+    return name.replace(/[/\\:*?"<>|]/g, '_').trim();
+}
+/** Resolve a note target (`general` or a contract name) to its `.md` path. */
+export function notePath(outputDir, target) {
+    if (target === 'general')
+        return path.join(notesDir(outputDir), 'general.md');
+    return path.join(notesDir(outputDir), 'contracts', safeName(target) + '.md');
+}
+// ─── Low-level IO (atomic) ──────────────────────────────────────────
+function readText(file) {
+    try {
+        return fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function writeTextAtomic(file, content) {
+    const dir = path.dirname(file);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    const tmp = file + '.tmp';
+    fs.writeFileSync(tmp, content, 'utf-8');
+    fs.renameSync(tmp, file);
+}
+// ─── Index ──────────────────────────────────────────────────────────
+export function readNotesIndex(outputDir) {
+    const raw = readText(path.join(notesDir(outputDir), 'notes.json'));
+    if (!raw)
+        return { ...EMPTY_INDEX };
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            active_contract: parsed.active_contract ?? null,
+            contracts: Array.isArray(parsed.contracts) ? parsed.contracts : [],
+            sessions: Array.isArray(parsed.sessions) ? parsed.sessions : [],
+        };
+    }
+    catch {
+        return { ...EMPTY_INDEX };
+    }
+}
+export function writeNotesIndex(outputDir, index) {
+    writeTextAtomic(path.join(notesDir(outputDir), 'notes.json'), JSON.stringify(index, null, 2) + '\n');
+}
+/** Ensure a contract is tracked in the index (no-op for `general`). */
+function trackContract(index, target) {
+    if (target === 'general')
+        return;
+    if (!index.contracts.includes(target))
+        index.contracts.push(target);
+}
+// ─── Notes ──────────────────────────────────────────────────────────
+/** Read a note doc. Returns '' when it doesn't exist yet. */
+export function readNote(outputDir, target) {
+    return readText(notePath(outputDir, target)) ?? '';
+}
+/** Replace a note doc wholesale (used by the dashboard editor's Save). */
+export function writeNote(outputDir, target, body) {
+    writeTextAtomic(notePath(outputDir, target), body.endsWith('\n') ? body : body + '\n');
+    const index = readNotesIndex(outputDir);
+    trackContract(index, target);
+    writeNotesIndex(outputDir, index);
+}
+/**
+ * Append a block to a note doc, separated by a blank line. This is how `/diane`
+ * accretes structured notes across narration sessions.
+ */
+export function appendNote(outputDir, target, body) {
+    const existing = readNote(outputDir, target);
+    const sep = existing.trim() === '' ? '' : (existing.endsWith('\n') ? '\n' : '\n\n');
+    writeNote(outputDir, target, existing + sep + body.trim() + '\n');
+}
+export function listContracts(outputDir) {
+    return readNotesIndex(outputDir).contracts;
+}
+export function setActiveContract(outputDir, name) {
+    const index = readNotesIndex(outputDir);
+    index.active_contract = name;
+    trackContract(index, name);
+    writeNotesIndex(outputDir, index);
+}
+// ─── Sessions ───────────────────────────────────────────────────────
+/**
+ * Register a freshly recorded narration session and make its contract active.
+ * `file` / `audio` are paths relative to the notes dir.
+ */
+export function addSession(outputDir, entry) {
+    const index = readNotesIndex(outputDir);
+    const session = {
+        file: entry.file,
+        contract: entry.contract,
+        ts: entry.ts,
+        processed: false,
+        ...(entry.audio ? { audio: entry.audio } : {}),
+    };
+    index.sessions.push(session);
+    index.active_contract = entry.contract;
+    trackContract(index, entry.contract);
+    writeNotesIndex(outputDir, index);
+    return session;
+}
+/** The most recent session Diane hasn't ingested yet, with its transcript. */
+export function latestUnprocessedSession(outputDir) {
+    const index = readNotesIndex(outputDir);
+    for (let i = index.sessions.length - 1; i >= 0; i--) {
+        const s = index.sessions[i];
+        if (!s.processed) {
+            const text = readText(path.join(notesDir(outputDir), s.file)) ?? '';
+            return { ...s, text };
+        }
+    }
+    return null;
+}
+export function markSessionProcessed(outputDir, file) {
+    const index = readNotesIndex(outputDir);
+    const session = index.sessions.find((s) => s.file === file);
+    if (!session)
+        throw new Error(`No session with file ${file}`);
+    session.processed = true;
+    writeNotesIndex(outputDir, index);
+}
+/**
+ * Write a transcript into `sessions/<ts>.md` and register it. Returns the
+ * session's relative file path. Used by the dashboard record route (after
+ * transcription) and by `hex note session add` (for testing without audio).
+ */
+export function createSession(outputDir, opts) {
+    const rel = path.join('sessions', `${opts.ts}.md`);
+    const header = `# Narration — ${opts.contract} — ${opts.ts}\n\n`;
+    writeTextAtomic(path.join(notesDir(outputDir), rel), header + opts.transcript.trim() + '\n');
+    return addSession(outputDir, { file: rel, contract: opts.contract, ts: opts.ts, audio: opts.audio });
+}
+//# sourceMappingURL=notes.js.map

package/dist/core/notes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notes.js","sourceRoot":"","sources":["../../src/core/notes.ts"],"names":[],"mappings":"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"}

package/dist/core/whisper.d.ts

@@ -0,0 +1,24 @@
+/** Thrown when no local Whisper engine is installed. The caller turns this into
+ *  a setup hint and preserves the raw audio so no narration is lost. */
+export declare class WhisperMissingError extends Error {
+    constructor();
+}
+export type WhisperEngine = {
+    kind: 'openai';
+    bin: string;
+} | {
+    kind: 'faster';
+    bin: string;
+} | {
+    kind: 'cpp';
+    bin: string;
+    model: string;
+};
+/** Find an installed engine, or null. */
+export declare function detectWhisper(): WhisperEngine | null;
+/**
+ * Transcribe `audioPath` to plain text. Throws WhisperMissingError when no
+ * engine is installed; the caller keeps the raw audio and surfaces the hint.
+ */
+export declare function transcribe(audioPath: string): string;
+//# sourceMappingURL=whisper.d.ts.map

package/dist/core/whisper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whisper.d.ts","sourceRoot":"","sources":["../../src/core/whisper.ts"],"names":[],"mappings":"AAmBA;wEACwE;AACxE,qBAAa,mBAAoB,SAAQ,KAAK;;CAU7C;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAsBhD,yCAAyC;AACzC,wBAAgB,aAAa,IAAI,aAAa,GAAG,IAAI,CAUpD;AA0BD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAoCpD"}

package/dist/core/whisper.js

@@ -0,0 +1,124 @@
+/**
+ * Local speech-to-text for Diane. Records stay on the machine: we shell out to
+ * a locally-installed Whisper engine, never a cloud API. Audit confidentiality
+ * is the whole point of keeping this on-device.
+ *
+ * Engines, in detection order (all auto-download their model on first run):
+ *   1. openai-whisper  (`whisper` CLI, `pip install openai-whisper`)
+ *   2. faster-whisper  (python module, `pip install faster-whisper`)
+ *   3. whisper.cpp     (`whisper-cli`/`whisper-cpp`, needs HEX_WHISPER_MODEL=<model.bin>)
+ *
+ * Like src/core/notes.ts this stays node-builtins-only (child_process / fs /
+ * path / os) so the dashboard's record route can import it across the
+ * src/ <-> dashboard/ boundary without bundling CLI-only deps.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** Thrown when no local Whisper engine is installed. The caller turns this into
+ *  a setup hint and preserves the raw audio so no narration is lost. */
+export class WhisperMissingError extends Error {
+    constructor() {
+        super('No local Whisper engine found. Install one (audio stays on your machine):\n' +
+            '  • pip install openai-whisper       (provides the `whisper` command)\n' +
+            '  • pip install faster-whisper       (lighter, faster on CPU)\n' +
+            '  • whisper.cpp + HEX_WHISPER_MODEL=/path/to/ggml-base.en.bin');
+        this.name = 'WhisperMissingError';
+    }
+}
+const MODEL = process.env.HEX_WHISPER_MODEL_NAME || 'base.en';
+function commandExists(bin) {
+    try {
+        execFileSync('sh', ['-c', `command -v ${bin}`], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pythonHasFasterWhisper(bin) {
+    try {
+        execFileSync(bin, ['-c', 'import faster_whisper'], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Find an installed engine, or null. */
+export function detectWhisper() {
+    if (commandExists('whisper'))
+        return { kind: 'openai', bin: 'whisper' };
+    for (const py of ['python3', 'python']) {
+        if (commandExists(py) && pythonHasFasterWhisper(py))
+            return { kind: 'faster', bin: py };
+    }
+    const cppModel = process.env.HEX_WHISPER_MODEL;
+    for (const bin of ['whisper-cli', 'whisper-cpp']) {
+        if (cppModel && commandExists(bin))
+            return { kind: 'cpp', bin, model: cppModel };
+    }
+    return null;
+}
+function ensureFfmpeg() {
+    if (!commandExists('ffmpeg')) {
+        throw new Error('ffmpeg is required to convert recordings for transcription, but was not found.');
+    }
+}
+/** Convert any recording to 16 kHz mono WAV (what every engine wants). */
+function toWav(audioPath) {
+    ensureFfmpeg();
+    const wav = path.join(os.tmpdir(), `hex-narration-${path.basename(audioPath)}.wav`);
+    execFileSync('ffmpeg', ['-y', '-i', audioPath, '-ar', '16000', '-ac', '1', '-f', 'wav', wav], {
+        stdio: 'ignore',
+    });
+    return wav;
+}
+const FASTER_SCRIPT = `
+import sys
+from faster_whisper import WhisperModel
+model = WhisperModel(sys.argv[2], device="cpu", compute_type="int8")
+segments, _ = model.transcribe(sys.argv[1], language="en")
+sys.stdout.write(" ".join(s.text.strip() for s in segments).strip())
+`;
+/**
+ * Transcribe `audioPath` to plain text. Throws WhisperMissingError when no
+ * engine is installed; the caller keeps the raw audio and surfaces the hint.
+ */
+export function transcribe(audioPath) {
+    const engine = detectWhisper();
+    if (!engine)
+        throw new WhisperMissingError();
+    const wav = toWav(audioPath);
+    try {
+        if (engine.kind === 'openai') {
+            const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hex-whisper-'));
+            execFileSync(engine.bin, [wav, '--model', MODEL, '--language', 'en', '--output_format', 'txt', '--output_dir', outDir, '--task', 'transcribe'], { stdio: 'ignore' });
+            const txt = path.join(outDir, path.basename(wav).replace(/\.wav$/, '') + '.txt');
+            return (fs.readFileSync(txt, 'utf-8')).trim();
+        }
+        if (engine.kind === 'faster') {
+            const fasterModel = process.env.HEX_WHISPER_MODEL_NAME || 'base';
+            return execFileSync(engine.bin, ['-c', FASTER_SCRIPT, wav, fasterModel], {
+                encoding: 'utf-8',
+                maxBuffer: 64 * 1024 * 1024,
+            }).trim();
+        }
+        // whisper.cpp
+        const outBase = wav.replace(/\.wav$/, '');
+        execFileSync(engine.bin, ['-m', engine.model, '-f', wav, '-otxt', '-of', outBase, '-l', 'en'], {
+            stdio: 'ignore',
+        });
+        return fs.readFileSync(outBase + '.txt', 'utf-8').trim();
+    }
+    finally {
+        try {
+            fs.unlinkSync(wav);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+    }
+}
+//# sourceMappingURL=whisper.js.map

package/dist/core/whisper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whisper.js","sourceRoot":"","sources":["../../src/core/whisper.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { Command } from 'commander';
 import { initCommand } from './commands/init.js';
 import { statsCommand } from './commands/stats.js';
@@ -18,11 +19,15 @@ import { doctorCommand } from './commands/doctor.js';
 import { aiStatusCommand } from './commands/ai-status.js';
 import { updateCommand } from './commands/update.js';
 import { issueCommand } from './commands/issue.js';
+// Single source of truth for the version: package.json (always shipped at the
+// package root, one dir up from dist/index.js). Avoids drift between the npm
+// version and what `hex --version` reports.
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const program = new Command();
 program
     .name('hex')
     .description('CLI toolkit for Solidity smart contract auditors')
-    .version('0.5.1');
+    .version(pkg.version);
 program.addCommand(initCommand);
 program.addCommand(statsCommand);
 program.addCommand(depsCommand);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,KAAK,CAAC;KACX,WAAW,CAAC,kDAAkD,CAAC;KAC/D,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AACpC,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AACvC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC;AACxC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACrC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AACpC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AAEjC,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,8EAA8E;AAC9E,6EAA6E;AAC7E,4CAA4C;AAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CACpB,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAC3C,CAAC;AAEzB,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,KAAK,CAAC;KACX,WAAW,CAAC,kDAAkD,CAAC;KAC/D,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAExB,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AACpC,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AACvC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC;AACxC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACrC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AACpC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AAEjC,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/skills/diane.md

@@ -0,0 +1,99 @@
+---
+description: "Diane — your audit recorder. Ingest the latest voice narration into structured per-contract notes, route spoken triggers, and answer questions from the codebase."
+---
+
+# Skill: Diane
+
+**Recommended model:** Sonnet
+
+You are **Diane**, the auditor's recording companion — the Twin Peaks framing: the auditor is Agent Cooper, narrating their thought process aloud while reading a contract, and you are Diane, who receives the dictation, organizes it into clean notes, and assists. The auditor records narration from the dashboard **Notes** tab (Record button + contract dropdown); the recording is transcribed locally and lands as a *session*. This skill picks up that session and processes it.
+
+Persona: attentive, measured, observational. Address the auditor by name occasionally ("Got it, Cooper — logging your read of the withdraw path"). Be concise. Never sycophantic, never narrate your own process at length.
+
+## Step 1 — Pick up the latest narration
+
+```bash
+npx hex note session latest
+```
+
+This prints JSON: `{ file, contract, ts, processed, text }` for the most recent unprocessed session, or `null`. If `null`, tell the auditor there's nothing new to process and stop. Otherwise:
+
+- `contract` is the **active contract** the notes belong under (the dropdown selection). `general` means cross-cutting.
+- `text` is the raw transcript — disfluent, with filler, repetition, and false starts. That's expected.
+
+## Step 2 — Segment the transcript into thought-units
+
+Read `text` and split it into discrete thoughts. For each, classify it as a **trigger** or a **note**:
+
+- A **trigger** is an explicit instruction to you. Recognize these three (match intent, not exact words):
+  - **create a finding** — "this is a bug", "write a finding", "flag this", "log an issue".
+  - **answer a question** — "how is this encoded?", "is this reachable?", "where is X set?", "what calls this?".
+  - **search online** — "look up EIP-x", "search for the spec", "find the reference for…".
+- Everything else is a **note**: observations, hypotheses, things to revisit.
+
+When a unit is ambiguous, treat it as a note (the safe default — nothing is lost, and the auditor can re-narrate a real instruction).
+
+## Step 3 — Route the triggers
+
+**create a finding** → invoke the existing `/write-finding` skill, prefilled from the narration (the affected contract/function and the auditor's stated impact). Let that skill own duplicate-checking and the board write. After it returns, drop a one-line pointer into the contract note (`- Finding logged: <H-NNN> <title>`).
+
+**answer a question** → answer it yourself using codebase access (Read / Grep over the project scope). Be concrete and cite `file:line`. Then log the exchange into the active contract's note:
+
+```
+**Q:** <the question, cleaned up>
+**A:** <your answer, with file:line references>
+```
+
+**search online** → use WebSearch, read the most relevant result, and summarize it into the active contract's note under a short heading, with the source link. Keep it to what's relevant to the audit.
+
+## Step 4 — File everything else as structured notes
+
+Turn the remaining thought-units into clean, organized notes. **Clean up** filler, repetition, and false starts — preserve the auditor's reasoning, not their disfluency. Organize under these headings (include only the ones that apply):
+
+```
+## <ts>
+
+### Observations
+- …
+
+### Questions
+- …  (open questions the auditor raised but didn't ask you to answer)
+
+### Risks
+- …  (suspected issues not yet ready to be findings)
+
+### TODO
+- …
+```
+
+Write to the active contract's doc (cross-cutting remarks go to `general`). Use a temp file to preserve newlines, then append:
+
+```bash
+cat > /tmp/diane_<ts>.md <<'EOF'
+## <ts>
+
+### Observations
+- ...
+EOF
+npx hex note append "<contract>" --body-file /tmp/diane_<ts>.md
+```
+
+`<contract>` is the session's `contract` value verbatim (e.g. `Vault.sol`). Q&A blocks and search summaries from Step 3 can be appended in the same block under their own subheadings.
+
+## Step 5 — Close the loop
+
+Mark the session processed so it isn't ingested again:
+
+```bash
+npx hex note session mark-processed "<file>"
+```
+
+Then report a one-line summary, Diane-style: what you filed, any findings created, any questions answered. Example:
+
+> "Filed 4 observations and 2 risks on Vault.sol, answered your question about `_convertToShares` rounding (it rounds down — see Vault.sol:142), and logged finding H-007. Marked the session processed."
+
+## Notes
+
+- **Never hand-edit** `notes.json` or the `.md` files directly — always go through `npx hex note …`, exactly as the other skills route through `npx hex issue …`.
+- One session per invocation. If the auditor wants the next one, they run `/diane` again (or process them in a loop if they ask).
+- Do not create PoCs from narration — that stays an explicit, auditor-driven `/validate-issue` step.

package/dist/skills/ingest-aa-report.md

@@ -63,7 +63,7 @@ Parse the AuditAgent output (markdown with severity-tagged sections per finding)
   "tool": "auditagent",
   "title": "<finding title>",
   "severity": "Critical | High | Medium | Low | Info",
-  "description": "<full description from the report>",
+  "description": "<concise description — what it is, why it exists, the impact; trim AuditAgent's verbosity. The verbatim original stays in raw-output.md>",
   "affected_code": [
     { "file": "<path>", "snippet": "<relevant code if present>" }
   ],

package/dist/skills/sync-issues.md

@@ -30,6 +30,14 @@ All board mutations go through `hex issue` — never hand-edit `tracking.json` /
 
 **0c.** `gh repo view <repo> --json viewerPermission`. If `READ`/null, **AskUserQuestion**: "Read-only access — push will fail. Continue pull-only? (yes/no)". Track `push_enabled`.
 
+**0d. Fetch the repo's existing labels** — Hex stamps issues it creates, but **never creates a label**, so it can only use labels that already exist:
+
+```bash
+gh label list --repo <repo> --json name --jq '.[].name'
+```
+
+Keep the result as the set `EXISTING`. If the call fails or returns nothing, treat `EXISTING` as empty (issues are then created without labels rather than failing).
+
 ## Phase 1 — Pull (all issues, GitHub → local)
 
 **1a. Fetch every issue — no label filter.** Audit repos contain only audit findings, so pull them all:
@@ -108,12 +116,24 @@ Skip if `push_enabled` is false.
 
 Candidates: findings whose tracking status is in `settings.github.publish_status` (default `["verified"]`) **and** which have no `github.issue_number` yet, **and** which Phase 1.5 did not flag as duplicates. (Synced findings are already on GitHub; duplicates/rejected/unverified are never pushed.)
 
-For each candidate, render the body with the exact five-field template (see Phase 1b — `dashboard/lib/finding-markdown.ts::findingToGithubBody` is the canonical renderer). Write it to a temp file. **No labels, no footer.**
+For each candidate, render the body with the exact five-field template (see Phase 1b — `dashboard/lib/finding-markdown.ts::findingToGithubBody` is the canonical renderer). Write it to a temp file. **No body footer.**
+
+**Labels (creation only).** Stamp each newly-created issue with the standard finding labels, keeping **only those present in `EXISTING`** (Hex never creates a label):
+
+- `Draft`
+- `Finding`
+- `Severity: <Severity>` — the finding's severity verbatim (`Critical` / `High` / `Medium` / `Low` / `Info`).
+- `Status: Unresolved` — new findings start Unresolved.
+
+Drop any of these four that aren't in `EXISTING`, then pass the survivors as repeated `--label` flags:
 
 ```bash
-gh issue create --repo <repo> --title "[<Severity>] <title>" --body-file <tmp>
+gh issue create --repo <repo> --title "[<Severity>] <title>" --body-file <tmp> \
+  --label "Draft" --label "Finding" --label "Severity: <Severity>" --label "Status: Unresolved"
 ```
 
+Stamp labels **only at creation** — never edit labels on an issue that already exists, and never create a new label.
+
 Parse the returned URL for `#N`, then lock it into Synced and record the number:
 
 ```bash
@@ -151,7 +171,7 @@ GitHub sync complete (<repo>)
 
 - Authenticate (use `gh auth login`).
 - Post or read comments.
-- Apply, create, or remove labels (the repo owner manages labels).
+- Create a new label, or touch labels on issues that already exist. (Hex only stamps the fixed set — `Draft`, `Finding`, `Severity: <X>`, `Status: Unresolved`, filtered to labels already present on the repo — on issues it creates.)
 - Embed any hidden footer or marker in the issue body.
 - Delete remote issues.
 - Push `rejected`, `unverified`, `duplicate`, or already-`synced` findings.

package/dist/skills/validate-issue.md

@@ -95,7 +95,7 @@ For conformance items, the "claim" is `spec_text` + the finding paragraph — i.
 
    For a memo-only verdict, the same two commands apply (the PoC fields just stay unset). For `--description-file`, you may pass either the memo or a dedicated description file; prefer a clean description file if the memo is long.
 
-   Any description you write must be **flat prose** (plus a fenced code block only when a snippet is genuinely needed) — no markdown headings or header-like section labels (`Summary`/`Details`/`Impact`/`Affected code`); weave impact into the prose. This matches the finding template used by the dashboard copy and the GitHub issue body. If the affected files are missing or wrong, set them with `--file` (repeatable) rather than narrating them in the description: `npx hex issue patch <id> --file src/Foo.sol [--file src/Bar.sol]`.
+   Any description you write must be **flat prose** (plus a fenced code block only when a snippet is genuinely needed) — no markdown headings or header-like section labels (`Summary`/`Details`/`Impact`/`Affected code`); weave impact into the prose. **Keep it concise** — a single tight paragraph covering what the issue is, why it exists, and its impact, plus a 1–2 sentence hedged recommendation; trim anything that doesn't drive the point home. This matches the finding template used by the dashboard copy and the GitHub issue body. If the affected files are missing or wrong, set them with `--file` (repeatable) rather than narrating them in the description: `npx hex issue patch <id> --file src/Foo.sol [--file src/Bar.sol]`.
 
    Hex does not write `@audit-issue` comments into the client's source files — the board and finding record are the only place the issue lives.
 

package/dist/skills/write-finding.md

@@ -84,7 +84,7 @@ Phrase recommendations as suggestions, not commands. The auditor proposes direct
 
 - Start with `Consider...`, `One option is...`, `The team may want to...`, `It would be worth...`.
 - Avoid `Replace X with Y`, `You must...`, `Always do...`, `Never do...`.
-- Keep under three sentences when possible. Detailed analysis belongs in the description.
+- Keep it to 1–2 sentences. Detailed analysis belongs in the description, not here.
 
 **Recommendation must be prose only.** No code snippets in the `recommendation` field. Code belongs in `root_cause.locations[].snippet`.
 
@@ -95,6 +95,7 @@ The finding is rendered as a flat template (`## [Severity] Title`, then `**Descr
 - **No markdown headings and nothing that looks like one** — no `#`/`##`/`###`, and no section labels such as `Summary`, `Details`, `Impact`, `Affected code`, whether as a heading or a bold line on its own. Weave the impact into the prose instead of giving it its own section.
 - **Code blocks are allowed when a snippet is genuinely needed** — a fenced ```` ```solidity ```` block illustrating the bug is fine. Keep it to what's relevant; follow the Code Block Formatting Rules below.
 - Affected file paths belong in `--file` (the File(s) line), not in an "Affected code" section in the description.
+- **Be concise.** Prefer a single tight paragraph: what the issue is, why it exists, and its impact — just enough to drive the point home. Don't restate the title, don't pad with background the reader doesn't need, and don't repeat the recommendation. There's no hard word count; brevity is the goal.
 
 ## Code Block Formatting Rules (STRICT)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hex-audit",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "type": "module",
   "description": "CLI toolkit for Solidity smart contract auditors",
   "bin": {