harnessgap 0.1.0

package/dist/output/human.js

@@ -0,0 +1,83 @@
+// Pure human-readable leaderboard formatter (the §8 table). Turns area rows +
+// summary + warnings into a column-aligned string. No I/O, no raw prose — only
+// area keys, counts, scores, and signal display strings appear in the output.
+// Fixed column widths for the leaderboard table.
+const AREA_W = 32;
+const FLAGGED_W = 8;
+const MEAN_W = 11;
+// Fixed canonical order + human labels for the warnings line. Zero-count
+// categories are omitted from the output.
+const WARNING_PARTS = [
+    { key: 'malformed_lines', label: 'malformed lines' },
+    { key: 'oversized_lines', label: 'oversized lines' },
+    { key: 'skipped_sessions', label: 'skipped sessions' },
+    { key: 'truncated_sessions', label: 'truncated sessions' },
+    { key: 'symlinks_rejected', label: 'symlinks rejected' },
+    { key: 'unresolvable_cwd', label: 'unresolvable cwd' },
+];
+/**
+ * Format the scan leaderboard as a human-readable string. Pure.
+ *
+ * Layout: header line, column-aligned table (or a "no flagged areas" line when
+ * empty), summary line, and a warnings line (only non-zero categories). The
+ * bootstrap count in the summary line is `sessionCount` when mode is bootstrap,
+ * else 0.
+ */
+export function formatHuman(input) {
+    const { repo, mode, sessionCount, areas, summary, warnings } = input;
+    const lines = [];
+    lines.push(`harnessgap scan — repo: ${repo} · ${sessionCount} sessions · mode: ${mode}`);
+    if (areas.length === 0) {
+        lines.push('No flagged areas.');
+    }
+    else {
+        lines.push(tableHeader());
+        for (const area of areas) {
+            lines.push(tableRow(area));
+        }
+    }
+    const bootCount = mode === 'bootstrap' ? sessionCount : 0;
+    lines.push(`${summary.flagged} areas flagged · ${summary.unflagged} unflagged · ${summary.unlocalized} unlocalized · bootstrap: ${bootCount} sessions`);
+    const wLine = warningsLine(warnings);
+    if (wLine !== null)
+        lines.push(wLine);
+    return lines.join('\n');
+}
+/** The column-header row, aligned to match the data rows. */
+function tableHeader() {
+    return `${'AREA'.padEnd(AREA_W)} | ${'FLAGGED'.padStart(FLAGGED_W)} | ${'MEAN SCORE'.padStart(MEAN_W)} | TOP SIGNALS`;
+}
+/** One area row, column-aligned. */
+function tableRow(area) {
+    const areaCol = fit(area.key, AREA_W);
+    const flaggedCol = String(area.sessions_flagged).padStart(FLAGGED_W);
+    const meanCol = area.mean_score.toFixed(1).padStart(MEAN_W);
+    const signalsCol = area.top_signals.map((t) => t.display).join(', ');
+    return `${areaCol} | ${flaggedCol} | ${meanCol} | ${signalsCol}`;
+}
+/**
+ * Fit a string to `width`: pad with spaces if shorter, truncate with "..." if
+ * longer. Keeps the column alignment intact.
+ */
+function fit(s, width) {
+    if (s.length <= width)
+        return s.padEnd(width);
+    return s.slice(0, width - 3) + '...';
+}
+/**
+ * Build the warnings line as `warnings: <n> <label>, <n> <label>`, omitting any
+ * category whose count is 0. Returns null when every category is 0 (line
+ * omitted entirely).
+ */
+function warningsLine(warnings) {
+    const parts = [];
+    for (const { key, label } of WARNING_PARTS) {
+        const count = warnings[key];
+        if (count > 0)
+            parts.push(`${count} ${label}`);
+    }
+    if (parts.length === 0)
+        return null;
+    return `warnings: ${parts.join(', ')}`;
+}
+//# sourceMappingURL=human.js.map

package/dist/output/human.js.map

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

package/dist/output/json.d.ts

@@ -0,0 +1,17 @@
+import type { AreaRow, JsonOutput, ScoringMode, StruggleRecord, Warnings } from '../types.js';
+/** Inputs to `buildJsonEnvelope`; all fields projected verbatim onto JsonOutput. */
+interface JsonEnvelopeInput {
+    repo: string;
+    mode: ScoringMode;
+    session_count: number;
+    warnings: Warnings;
+    sessions: StruggleRecord[];
+    areas: AreaRow[];
+}
+/**
+ * Assemble the `JsonOutput` envelope. Pure: returns a new object whose fields
+ * are the inputs plus `schema_version: 1`. Does not clone `sessions`/`areas`
+ * (callers may share references; the envelope is read-only by contract).
+ */
+export declare function buildJsonEnvelope(input: JsonEnvelopeInput): JsonOutput;
+export {};

package/dist/output/json.js

@@ -0,0 +1,22 @@
+// Pure JSON envelope assembler. Turns the detector + aggregator outputs into
+// the `JsonOutput` shape consumed by the `--json` CLI flag. No I/O, no
+// transformation beyond direct field projection: sessions and areas are passed
+// through as-is (already scrubbed of prose upstream), warnings are integer
+// counts. schema_version is pinned to 1.
+/**
+ * Assemble the `JsonOutput` envelope. Pure: returns a new object whose fields
+ * are the inputs plus `schema_version: 1`. Does not clone `sessions`/`areas`
+ * (callers may share references; the envelope is read-only by contract).
+ */
+export function buildJsonEnvelope(input) {
+    return {
+        schema_version: 1,
+        repo: input.repo,
+        mode: input.mode,
+        session_count: input.session_count,
+        warnings: input.warnings,
+        sessions: input.sessions,
+        areas: input.areas,
+    };
+}
+//# sourceMappingURL=json.js.map

package/dist/output/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/output/json.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,uEAAuE;AACvE,+EAA+E;AAC/E,2EAA2E;AAC3E,yCAAyC;AAoBzC;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAwB;IACxD,OAAO;QACL,cAAc,EAAE,CAAC;QACjB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,KAAK,EAAE,KAAK,CAAC,KAAK;KACnB,CAAC;AACJ,CAAC"}

package/dist/pipeline.d.ts

@@ -0,0 +1,24 @@
+import type { ScoringMode, Warnings } from './types.js';
+export interface ScanOptions {
+    repo?: string;
+    since?: string;
+    limit?: number;
+    json?: boolean;
+    calibrate?: boolean;
+    bootstrap?: boolean;
+    configPath?: string;
+    claudeDir?: string;
+}
+export interface ScanResult {
+    output: string;
+    mode: ScoringMode;
+    sessionCount: number;
+    warnings: Warnings;
+    exitCode: 0 | 1;
+}
+/**
+ * Orchestrate the full harnessgap scan. Async (awaits streamSession +
+ * resolveToplevel). Returns the output string, mode, session count, aggregated
+ * warnings, and exitCode (always 0 — misconfig throws propagate to the CLI).
+ */
+export declare function runScan(opts: ScanOptions): Promise<ScanResult>;

package/dist/pipeline.js

@@ -0,0 +1,164 @@
+// Stateless scan pipeline — the thin I/O shell that orchestrates walk → stream
+// → git-resolve → detect → aggregate → output. All pure logic lives in the
+// modules it composes; this file threads them together, applies filters, and
+// branches the output form. No disk writes, no network. Async because
+// streamSession and resolveToplevel are async.
+//
+// Filter / mode / output-branching choices (documented here, pinned to the
+// task-16 brief + resolution notes):
+//
+// - repo filter when opts.repo is unset: resolve `resolveToplevel(process.cwd())`.
+//   If it resolves, filter envelopes to that toplevel; if it does NOT resolve
+//   (process.cwd() is not a repo), keep ALL envelopes with a non-empty repo.
+// - mode when no records: "bootstrap" (consistent with scoreSessions: 0 sessions
+//   < bootstrap_session_floor → bootstrap).
+// - repo for output: the filtered repo (opts.repo, or the resolved process.cwd()
+//   toplevel, or "" if neither resolves).
+// - --since: parseDuration(opts.since) → ms (Infinity → no filter). Filter:
+//   Date.parse(started_at) >= now − sinceMs. Empty/unparseable started_at →
+//   excluded (can't date it).
+// - --limit: applied AFTER all filtering. Negative limits are ignored.
+// - empty cwd (streamSession returned cwd=''): treated as unresolvable
+//   (unresolvable_cwd++, skipped) — resolveToplevel('') would wrongly resolve
+//   process.cwd()'s repo.
+// - ConfigError from loadConfig / parseDuration is NOT caught here — it
+//   propagates to the CLI for non-zero exit. runScan's exitCode is always 0.
+import { loadConfig, parseDuration } from './config.js';
+import { discoverTranscripts, defaultClaudeDir } from './walk.js';
+import { streamSession } from './adapter/stream.js';
+import { resolveToplevel } from './git.js';
+import { runDetector } from './detector/index.js';
+import { aggregateAreas } from './aggregate/leaderboard.js';
+import { buildJsonEnvelope } from './output/json.js';
+import { formatHuman } from './output/human.js';
+import { buildCalibrateObject, formatCalibrateTable } from './output/calibrate.js';
+/**
+ * Orchestrate the full harnessgap scan. Async (awaits streamSession +
+ * resolveToplevel). Returns the output string, mode, session count, aggregated
+ * warnings, and exitCode (always 0 — misconfig throws propagate to the CLI).
+ */
+export async function runScan(opts) {
+    // 1. Load config (ConfigError propagates — not caught here).
+    const cfg = loadConfig(opts.configPath);
+    // 2. Discover transcripts.
+    const claudeDir = opts.claudeDir ?? defaultClaudeDir();
+    const { files, symlinks_rejected } = discoverTranscripts(claudeDir);
+    const warnings = {
+        malformed_lines: 0,
+        oversized_lines: 0,
+        skipped_sessions: 0,
+        truncated_sessions: 0,
+        symlinks_rejected,
+        unresolvable_cwd: 0,
+    };
+    // 3. Stream each file, resolve repo, accumulate warnings. Thread a single
+    //    git-cache across all sessions (cwd repeats are common across transcripts).
+    const cache = new Map();
+    const envelopes = [];
+    for (const file of files) {
+        const { envelope, cwd, warnings: streamWarnings } = await streamSession(file);
+        warnings.malformed_lines += streamWarnings.malformed_lines;
+        warnings.oversized_lines += streamWarnings.oversized_lines;
+        warnings.truncated_sessions += streamWarnings.truncated_sessions;
+        // Empty cwd → can't resolve a repo (resolveToplevel('') would resolve
+        // process.cwd()'s repo, which is wrong). Skip as unresolvable.
+        if (cwd === '') {
+            warnings.unresolvable_cwd += 1;
+            warnings.skipped_sessions += 1;
+            continue;
+        }
+        const toplevel = await resolveToplevel(cwd, cache);
+        if (!toplevel) {
+            warnings.unresolvable_cwd += 1;
+            warnings.skipped_sessions += 1;
+            continue;
+        }
+        envelope.repo = toplevel;
+        envelopes.push(envelope);
+    }
+    // 4. Filter by repo.
+    let filterRepo;
+    if (opts.repo !== undefined) {
+        filterRepo = opts.repo;
+    }
+    else {
+        const cwdToplevel = await resolveToplevel(process.cwd(), cache);
+        filterRepo = cwdToplevel ?? '';
+    }
+    let filtered;
+    if (filterRepo !== '') {
+        filtered = envelopes.filter((e) => e.repo === filterRepo);
+    }
+    else {
+        // process.cwd() didn't resolve and no opts.repo — keep all envelopes with
+        // a non-empty repo.
+        filtered = envelopes.filter((e) => e.repo !== '');
+    }
+    // 5. Apply --since (filter by started_at ≥ now − duration).
+    if (opts.since !== undefined) {
+        const sinceMs = parseDuration(opts.since);
+        if (sinceMs !== Infinity) {
+            const cutoff = Date.now() - sinceMs;
+            filtered = filtered.filter((e) => {
+                if (e.started_at === '')
+                    return false;
+                const t = Date.parse(e.started_at);
+                return !Number.isNaN(t) && t >= cutoff;
+            });
+        }
+    }
+    // Apply --limit (cap count, AFTER all filtering).
+    if (opts.limit !== undefined && opts.limit >= 0) {
+        filtered = filtered.slice(0, opts.limit);
+    }
+    // 6. Run detector.
+    const forceBootstrap = opts.bootstrap ?? false;
+    const records = runDetector(filtered, cfg, forceBootstrap);
+    // 7. Aggregate areas.
+    const { rows, summary } = aggregateAreas(records, cfg);
+    // 8. Determine mode (consistent across all records; default bootstrap when
+    //    no records — matches scoreSessions' selectMode for n=0).
+    const mode = records.length > 0 ? records[0].mode : 'bootstrap';
+    // repo for output: the repo envelopes were filtered to (or "" if none).
+    const outputRepo = filterRepo;
+    // 9. Build output — branch by --calibrate / --json / human.
+    let output;
+    if (opts.calibrate) {
+        const calObj = buildCalibrateObject({
+            mode,
+            session_count: records.length,
+            flag_pct: cfg.detector.flag_pct,
+            signals: records.map((r) => r.signals),
+            bootstrap_thresholds: cfg.detector.bootstrap_thresholds,
+        });
+        output = opts.json ? JSON.stringify(calObj) : formatCalibrateTable(calObj);
+    }
+    else if (opts.json) {
+        output = JSON.stringify(buildJsonEnvelope({
+            repo: outputRepo,
+            mode,
+            session_count: records.length,
+            warnings,
+            sessions: records,
+            areas: rows,
+        }));
+    }
+    else {
+        output = formatHuman({
+            repo: outputRepo,
+            mode,
+            sessionCount: records.length,
+            areas: rows,
+            summary,
+            warnings,
+        });
+    }
+    return {
+        output,
+        mode,
+        sessionCount: records.length,
+        warnings,
+        exitCode: 0,
+    };
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,122 @@
+export type ToolKind = 'read' | 'search' | 'list' | 'edit' | 'exec' | 'other';
+export type EventKind = 'user_msg' | 'assistant_msg' | 'tool_call';
+export type SignalName = 'explore_ratio' | 'reread' | 'failure_streak' | 'corrections' | 'abandonment' | 'oscillation' | 'wall_clock_per_line';
+export type ScoringMode = 'percentile' | 'bootstrap';
+export interface InputDigest {
+    files: string[];
+    cmd: string | null;
+    query: string | null;
+    lines_changed: number | null;
+}
+export interface Correction {
+    matched: boolean;
+    shape: string | null;
+}
+export interface NormalizedEvent {
+    t: string;
+    kind: EventKind;
+    tool: ToolKind | null;
+    input_digest: InputDigest;
+    ok: boolean;
+    interrupted: boolean;
+    duration_ms: number;
+    correction: Correction | null;
+}
+export interface NormalizedEnvelope {
+    schema_version: 1;
+    session_id: string;
+    agent: 'claude-code';
+    repo: string;
+    started_at: string;
+    duration_ms: number;
+    events: NormalizedEvent[];
+    truncated: boolean;
+    event_count: number;
+}
+export interface SignalValues {
+    explore_ratio: number | null;
+    reread: number;
+    failure_streak: number;
+    corrections: number;
+    abandonment: boolean;
+    oscillation: number;
+    wall_clock_per_line_ms: number | null;
+}
+export interface StruggleRecord {
+    session_id: string;
+    repo: string;
+    started_at: string;
+    duration_ms: number;
+    score_pct: number;
+    mode: ScoringMode;
+    flagged: boolean;
+    truncated: boolean;
+    event_count: number;
+    areas: {
+        key: string;
+        weight: number;
+    }[];
+    signals: SignalValues;
+}
+export interface Warnings {
+    malformed_lines: number;
+    oversized_lines: number;
+    skipped_sessions: number;
+    truncated_sessions: number;
+    symlinks_rejected: number;
+    unresolvable_cwd: number;
+}
+export interface AreaRow {
+    key: string;
+    sessions_total: number;
+    sessions_flagged: number;
+    mean_score: number;
+    top_signals: {
+        name: SignalName;
+        value: number | boolean;
+        display: string;
+    }[];
+}
+export interface JsonOutput {
+    schema_version: 1;
+    repo: string;
+    mode: ScoringMode;
+    session_count: number;
+    warnings: Warnings;
+    sessions: StruggleRecord[];
+    areas: AreaRow[];
+}
+export interface Config {
+    detector: {
+        thresholds_as: 'percentile' | 'absolute';
+        flag_pct: number;
+        bootstrap_session_floor: number;
+        bootstrap_flag_pct: number;
+        reread_threshold: number;
+        correction_window_ms: number;
+        signal_weights: Record<SignalName, number>;
+        bootstrap_thresholds: {
+            explore_ratio: number;
+            reread: number;
+            failure_streak: number;
+            corrections: number;
+            abandonment: boolean;
+            oscillation: number;
+            wall_clock_per_line_ms: number;
+        };
+    };
+    areas: {
+        ignore: string[];
+        min_weight: number;
+        min_depth: number;
+        touch_weights: {
+            edit: number;
+            read: number;
+            exec: number;
+        };
+        tail_fraction: number;
+        explore_ratio_min: number;
+        suppress_abandonment_when_no_exec: boolean;
+        test_cmd_patterns: string[];
+    };
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Shared type catalog for harnessgap. Every later task imports from here.
+// Field names and shapes are contracts pinned to the design spec.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,kEAAkE"}

package/dist/walk.d.ts

@@ -0,0 +1,12 @@
+/** Default Claude config directory: `~/.claude`. */
+export declare function defaultClaudeDir(): string;
+/**
+ * Discover all .jsonl transcripts under <claudeDir>/projects/<slug>/<file>.jsonl
+ * (exactly one session-dir level under projects/). Rejects symlinks (lstat,
+ * never followed) and confines results to the projects/ prefix. Fail-open on
+ * missing projects/ dir.
+ */
+export declare function discoverTranscripts(claudeDir: string): {
+    files: string[];
+    symlinks_rejected: number;
+};

package/dist/walk.js

@@ -0,0 +1,92 @@
+// Transcript discovery — finds every *.jsonl under
+// <claudeDir>/projects/*/*.jsonl (exactly one session-dir level under
+// projects/). Security-critical: NEVER follows symlinks.
+//
+// - Directory traversal uses readdir(withFileTypes): Dirent.isDirectory() is
+//   false for symlinks (even symlinks-to-dirs), so symlinked session-dirs are
+//   skipped at the directory level — never entered, never realpath'd.
+// - Each .jsonl candidate is lstat'd (not stat'd): a symlink .jsonl is rejected
+//   and counted in symlinks_rejected regardless of where it points.
+// - A defensive prefix-confinement check rejects any resolved path that escapes
+//   <claudeDir>/projects/ (guards against `..`-style traversal in dir names,
+//   which readdir itself never produces but we verify anyway).
+//
+// Does NOT read file contents (streamSession in adapter/stream.ts does that).
+// Fail-open: a missing or unreadable projects/ dir yields an empty result,
+// never a throw.
+//
+// Sync I/O is chosen deliberately: the pipeline walks a bounded number of
+// files and sync code avoids an await at every call site. Output is sorted
+// lexicographically so the pipeline sees a stable input order.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+/** Default Claude config directory: `~/.claude`. */
+export function defaultClaudeDir() {
+    return path.join(os.homedir(), '.claude');
+}
+/**
+ * Discover all .jsonl transcripts under <claudeDir>/projects/<slug>/<file>.jsonl
+ * (exactly one session-dir level under projects/). Rejects symlinks (lstat,
+ * never followed) and confines results to the projects/ prefix. Fail-open on
+ * missing projects/ dir.
+ */
+export function discoverTranscripts(claudeDir) {
+    const files = [];
+    let symlinks_rejected = 0;
+    const projectsDir = path.resolve(claudeDir, 'projects');
+    const prefix = projectsDir + path.sep;
+    let topEntries;
+    try {
+        topEntries = fs.readdirSync(projectsDir, { withFileTypes: true });
+    }
+    catch {
+        // Missing or unreadable projects/ dir — fail open.
+        return { files, symlinks_rejected };
+    }
+    for (const dirent of topEntries) {
+        // Exactly one session-dir level under projects/. isDirectory() is false
+        // for symlinks, so symlinked session-dirs are skipped here without being
+        // traversed or realpath'd.
+        if (!dirent.isDirectory())
+            continue;
+        const sessionDir = path.join(projectsDir, dirent.name);
+        let sessionEntries;
+        try {
+            sessionEntries = fs.readdirSync(sessionDir, { withFileTypes: true });
+        }
+        catch {
+            continue; // unreadable session-dir — skip
+        }
+        for (const fe of sessionEntries) {
+            if (!fe.name.endsWith('.jsonl'))
+                continue;
+            const candidate = path.join(sessionDir, fe.name);
+            let st;
+            try {
+                st = fs.lstatSync(candidate);
+            }
+            catch {
+                continue; // unreadable entry — skip
+            }
+            // lstat (not stat): never follows symlinks. A symlink .jsonl is rejected
+            // and counted, regardless of its target.
+            if (st.isSymbolicLink()) {
+                symlinks_rejected++;
+                continue;
+            }
+            if (!st.isFile())
+                continue; // dirs / sockets / fifos named *.jsonl
+            // Defensive confinement: the resolved absolute path must live under
+            // projects/. Belt-and-suspenders against path-traversal via `..` in dir
+            // names (readdir never emits such names, but we verify anyway).
+            const resolved = path.resolve(candidate);
+            if (!resolved.startsWith(prefix))
+                continue;
+            files.push(resolved);
+        }
+    }
+    files.sort();
+    return { files, symlinks_rejected };
+}
+//# sourceMappingURL=walk.js.map

package/dist/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,sEAAsE;AACtE,yDAAyD;AACzD,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,sEAAsE;AACtE,gFAAgF;AAChF,oEAAoE;AACpE,gFAAgF;AAChF,6EAA6E;AAC7E,+DAA+D;AAC/D,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,iBAAiB;AACjB,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,+DAA+D;AAE/D,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9B,oDAAoD;AACpD,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAiB;IAEjB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAE1B,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC;IAEtC,IAAI,UAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,UAAU,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,mDAAmD;QACnD,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC;IACtC,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;QAChC,wEAAwE;QACxE,yEAAyE;QACzE,2BAA2B;QAC3B,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE;YAAE,SAAS;QAEpC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QACvD,IAAI,cAA2B,CAAC;QAChC,IAAI,CAAC;YACH,cAAc,GAAG,EAAE,CAAC,WAAW,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACvE,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,gCAAgC;QAC5C,CAAC;QAED,KAAK,MAAM,EAAE,IAAI,cAAc,EAAE,CAAC;YAChC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAE,SAAS;YAE1C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;YACjD,IAAI,EAAY,CAAC;YACjB,IAAI,CAAC;gBACH,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;YAC/B,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS,CAAC,0BAA0B;YACtC,CAAC;YACD,yEAAyE;YACzE,yCAAyC;YACzC,IAAI,EAAE,CAAC,cAAc,EAAE,EAAE,CAAC;gBACxB,iBAAiB,EAAE,CAAC;gBACpB,SAAS;YACX,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE;gBAAE,SAAS,CAAC,uCAAuC;YAEnE,oEAAoE;YACpE,wEAAwE;YACxE,gEAAgE;YAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YACzC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;gBAAE,SAAS;YAE3C,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,EAAE,CAAC;IACb,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC;AACtC,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "harnessgap",
+  "version": "0.1.0",
+  "description": "Stateless detection-only CLI that finds harness gaps in Claude Code transcripts",
+  "license": "MIT",
+  "author": "Dmitry Teryaev",
+  "homepage": "https://github.com/HumanBean17/harnessgap#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HumanBean17/harnessgap.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HumanBean17/harnessgap/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "cli",
+    "transcripts",
+    "developer-tools",
+    "observability",
+    "agent-harness"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "bin": {
+    "harnessgap": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}