@avi770/testteam 2.0.0 → 3.2.0

package/dist/core/tech-debt/types.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Technical Debt Tracker (#20) — module-local types.
+ *
+ * Agent #20 is a continuous/composite operational layer that composes output
+ * from engine agents #68 (Dead Code), #69 (Type Safety), #70 (Complexity),
+ * and #83 (Static Analysis). It never re-scans; it orchestrates and annotates.
+ *
+ * Spec: blueprint/agents/20-technical-debt-tracker.md
+ */
+import type { Finding } from '../types.js';
+/** Snapshot of findings from one engine agent, keyed by file path. */
+export interface EngineFindings {
+    /** Source engine agent id (68 | 69 | 70 | 83). */
+    readonly agentId: number;
+    /** ISO timestamp of when these findings were collected. */
+    readonly capturedAt: string;
+    /** The raw findings produced by the engine agent. */
+    readonly findings: readonly Finding[];
+}
+/** Git churn record for a single file path. */
+export interface ChurnRecord {
+    /** Repo-relative file path. */
+    readonly filePath: string;
+    /** Number of commits that touched this file in the measurement window. */
+    readonly commitCount: number;
+    /** Optionally: authors who own the file (bus-factor source). */
+    readonly authors?: readonly string[];
+}
+/**
+ * Hotspot score for a single file.
+ * score = commitCount × complexityFindingCount  (never rounded up)
+ */
+export interface Hotspot {
+    readonly filePath: string;
+    readonly commitCount: number;
+    readonly complexityFindingCount: number;
+    /** Raw product — deliberately un-normalised so comparisons are meaningful. */
+    readonly score: number;
+}
+/**
+ * Debt category taxonomy.
+ *
+ * The first four are PRODUCED by this module from engine agents #68/#69/#70/#83
+ * (see `categoryForAgent`). The remaining four are RESERVED for debt sourced from
+ * inputs not yet wired into the engine path (manual entries, a dependency scanner,
+ * a duplication detector, an architecture review); their EFFORT/INTEREST calibration
+ * is forward-looking and is NOT currently emitted by `runTechDebtTracker`. (Note:
+ * `coverage-gap` is surfaced as the `hasCoverageGap` flag on a DebtItem, not as a
+ * category emitted by the engine path.)
+ */
+export type DebtCategory = 'dead-code' | 'type-safety' | 'complexity' | 'static-analysis' | 'coverage-gap' | 'dependency' | 'duplication' | 'architecture';
+/** A single quantified debt item derived from one or more engine findings. */
+export interface DebtItem {
+    readonly id: string;
+    readonly category: DebtCategory;
+    /** Source finding(s) that contributed to this item. */
+    readonly sourceFindings: readonly string[];
+    readonly filePath: string;
+    /** Human-readable description of the debt. */
+    readonly description: string;
+    /**
+     * Estimated fix effort in ideal engineer-hours.
+     * Never rounded up per Avi's QA standard — fractional values are fine.
+     */
+    readonly effortHours: number;
+    /**
+     * Estimated cost of NOT fixing: accumulation rate in hours/sprint.
+     * Represents interest on debt (slow-down, bug-probability increase).
+     */
+    readonly interestHoursPerSprint: number;
+    /**
+     * ROI = interestHoursPerSprint / effortHours.
+     * Higher is more worth fixing. Deterministic floating-point; never rounded.
+     */
+    readonly roi: number;
+    /** True when the file also has a hotspot score above threshold. */
+    readonly isHotspot: boolean;
+    /** True when the file has insufficient test coverage (Improvement #6). */
+    readonly hasCoverageGap: boolean;
+    /**
+     * Evidence chain: why this item is ranked where it is (Improvement #16).
+     * Every "fix first" candidate shows its math.
+     */
+    readonly priorityRationale: string;
+    /**
+     * If correlated with past bugs, carry the evidence label (Improvement #4).
+     * null means no historical correlation data available.
+     */
+    readonly bugCorrelation: string | null;
+    /**
+     * Bus-factor risk label (Improvement #12): 'sole-author' | 'shared' | null.
+     * null = no churn/author data supplied.
+     */
+    readonly knowledgeRisk: 'sole-author' | 'shared' | null;
+}
+/** A proposed refactoring task derived from one or more DebtItems. */
+export interface RefactorProposal {
+    readonly id: string;
+    /** Ordered position in the roadmap (1-based; dependency-aware). */
+    readonly sequence: number;
+    /** Debt items addressed by this refactor. */
+    readonly debtItemIds: readonly string[];
+    readonly title: string;
+    readonly rationale: string;
+    readonly estimatedEffortHours: number;
+    /**
+     * Always "tests-required" — no refactor ships without tests (Improvement #10).
+     * This field makes the constraint machine-readable for the gate.
+     */
+    readonly testsRequired: true;
+    /**
+     * Gate status lifecycle:
+     *   'proposed'            — initial state; auto-merge is blocked.
+     *   'gated-awaiting-human'— queued for human review; still blocked.
+     *   'approved'            — set externally by the harness after human sign-off;
+     *                           the only state that allows the refactor to proceed.
+     *   'rejected'            — human declined; permanently blocked.
+     *
+     * (Improvement #10, operating rule: never auto-merges a refactor.)
+     */
+    readonly gateStatus: 'proposed' | 'gated-awaiting-human' | 'approved' | 'rejected';
+}
+/** Ordered refactoring roadmap with dependency awareness (Improvement #5). */
+export interface RefactoringRoadmap {
+    readonly generatedAt: string;
+    /** Top-N proposals ordered by sequence (dependency-first, then ROI). */
+    readonly proposals: readonly RefactorProposal[];
+    /** Total estimated effort for all proposals combined (hours). */
+    readonly totalEffortHours: number;
+}
+export interface DebtBudget {
+    /** Maximum allowed total DebtItems above this count blocks a PR. */
+    readonly maxDebtItems: number;
+    /**
+     * Maximum allowed total effort-hours of open debt.
+     * If total exceeds this, blockPR = true.
+     */
+    readonly maxTotalEffortHours: number;
+}
+export interface BudgetCheckResult {
+    readonly status: 'ok' | 'exceeded';
+    readonly currentDebtItems: number;
+    readonly currentTotalEffortHours: number;
+    /** When exceeded=true the PR is blocked (Improvement #13). */
+    readonly blockPR: boolean;
+    readonly reason: string;
+}
+/**
+ * Describes the set of files changed in a PR/commit.
+ * When present, the tracker analyses ONLY these files (no full re-scan).
+ */
+export interface DiffScope {
+    /** Repo-relative paths of files changed in this PR/commit. */
+    readonly changedFiles: readonly string[];
+    /** Git SHA or PR identifier for provenance. */
+    readonly ref: string;
+}
+/**
+ * A historical record linking a file path to past bugs or incidents.
+ * Callers supply this from their issue tracker / incident log.
+ *
+ * When a DebtItem's filePath appears in the bug history the item receives a
+ * non-null `bugCorrelation` label (Improvement #4).
+ */
+export interface BugHistoryRecord {
+    /** Repo-relative file path that was involved in a bug or incident. */
+    readonly filePath: string;
+    /** Number of past bugs/incidents attributed to this file. */
+    readonly bugCount: number;
+    /**
+     * Optional free-text label describing the incident pattern
+     * (e.g. "null-pointer cluster 2026-Q1", "memory-leak sprint-22").
+     * Included verbatim in the debt item's bugCorrelation field.
+     */
+    readonly label?: string;
+}
+export interface DebtSnapshot {
+    readonly snapshotId: string;
+    readonly capturedAt: string;
+    readonly totalDebtItems: number;
+    readonly totalEffortHours: number;
+    readonly ref?: string;
+}
+export interface DebtTrend {
+    /** Chronological snapshots (oldest first). */
+    readonly snapshots: readonly DebtSnapshot[];
+    /**
+     * Net change in items from first to last snapshot.
+     * Negative = debt paid down; positive = debt accumulating.
+     */
+    readonly netItemDelta: number;
+    readonly netEffortDelta: number;
+}
+export interface TechDebtReport {
+    readonly reportId: string;
+    readonly generatedAt: string;
+    /**
+     * True when this was a diff-aware (partial) run.
+     * If false, it was a full sweep.
+     */
+    readonly isDiffAwareRun: boolean;
+    /** Repo-relative file paths actually analysed (subset when diff-aware). */
+    readonly filesAnalysed: readonly string[];
+    /** Ranked debt inventory (highest ROI first). */
+    readonly debtInventory: readonly DebtItem[];
+    /** Hotspots sorted by score descending. */
+    readonly hotspots: readonly Hotspot[];
+    /** Sequenced refactoring roadmap. */
+    readonly roadmap: RefactoringRoadmap;
+    /** Coverage-gap debt items subset. */
+    readonly coverageGaps: readonly DebtItem[];
+    /** Budget check result (if a budget was configured). */
+    readonly budgetCheck: BudgetCheckResult | null;
+    /**
+     * Debt trend vs prior snapshots (Improvement #15) — populated only when
+     * `priorSnapshots` was supplied on the input; `null` otherwise.
+     */
+    readonly trend: DebtTrend | null;
+}
+export interface TechDebtTrackerInput {
+    /** Findings from engine agent #68 (Dead Code Detector). */
+    readonly deadCodeFindings: EngineFindings;
+    /** Findings from engine agent #69 (Type Safety Auditor). */
+    readonly typeSafetyFindings: EngineFindings;
+    /** Findings from engine agent #70 (Complexity Analyzer). */
+    readonly complexityFindings: EngineFindings;
+    /** Findings from engine agent #83 (Static Analysis Agent). */
+    readonly staticAnalysisFindings: EngineFindings;
+    /**
+     * Git churn data for hotspot analysis (Improvement #2).
+     * If omitted, hotspot scores default to complexity-only (commitCount = 0).
+     */
+    readonly churnData?: readonly ChurnRecord[];
+    /**
+     * Per-file coverage percentage (0..100).
+     * Used to identify coverage gaps paired with risky debt (Improvement #6).
+     */
+    readonly coverageByFile?: Readonly<Record<string, number>>;
+    /**
+     * Coverage threshold below which a file is considered under-tested.
+     * Default: 60 (matching industry pragmatics).
+     */
+    readonly coverageThreshold?: number;
+    /**
+     * Optionally restrict analysis to changed files only (Improvement #1).
+     * When provided, only changed files produce debt items in this run.
+     */
+    readonly diffScope?: DiffScope;
+    /** Debt budget for ratchet enforcement (Improvement #13). */
+    readonly budget?: DebtBudget;
+    /** Historical snapshots for trend computation (Improvement #15). */
+    readonly priorSnapshots?: readonly DebtSnapshot[];
+    /**
+     * Historical bug/incident records used for correlation (Improvement #4).
+     * When provided, debt items whose filePath appears here receive a non-null
+     * `bugCorrelation` label showing bug count + optional pattern label.
+     * When omitted, all items carry bugCorrelation=null (no historical data).
+     */
+    readonly bugHistory?: readonly BugHistoryRecord[];
+    /** Clock override for deterministic testing. */
+    readonly clock?: () => string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/tech-debt/types.d.ts.map

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

package/dist/core/tech-debt/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/tech-debt/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../core/tech-debt/types.ts"],"names":[],"mappings":""}

package/dist/core/tester/diff-planner.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Diff-aware, risk-based test planning (Phase 3.1) — the frugality + prioritization core of #1.
+ * Tests only the surfaces that changed (near-zero steady cost) and runs the highest-risk/most-
+ * changed first. Composes #25's blast-radius via an optional per-agent boost map.
+ * Spec: blueprint/agents/01-testteam-bot.md (improvements #1 diff-aware, #2 risk-based).
+ */
+import type { AgentDescriptor, TestPlan } from './types.js';
+export interface PlanOptions {
+    /** Extra priority per agent (e.g. derived from #25 blast-radius size). */
+    readonly boosts?: ReadonlyMap<number, number>;
+}
+/**
+ * Build a test plan: select agents whose surfaces changed, skip the rest, and order the selected
+ * by priority = risk * (1 + matches) + boost (descending). Ties break by ascending agentId for
+ * determinism.
+ */
+export declare function planTests(changedFiles: readonly string[], descriptors: readonly AgentDescriptor[], options?: PlanOptions): TestPlan;
+//# sourceMappingURL=diff-planner.d.ts.map

package/dist/core/tester/diff-planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-planner.d.ts","sourceRoot":"","sources":["../../../core/tester/diff-planner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,eAAe,EAAoB,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE3E,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/C;AAYD;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,WAAW,EAAE,SAAS,eAAe,EAAE,EACvC,OAAO,CAAC,EAAE,WAAW,GACpB,QAAQ,CAsBV"}

package/dist/core/tester/diff-planner.js

@@ -0,0 +1,37 @@
+/** Count how many changed files fall within an agent's surfaces. */
+function matchCount(descriptor, changedFiles) {
+    let count = 0;
+    for (const file of changedFiles) {
+        // Guard empty-string surfaces — `includes('')` is always true (would match-all).
+        if (descriptor.surfaces.some((surface) => surface.length > 0 && file.includes(surface)))
+            count += 1;
+    }
+    return count;
+}
+/**
+ * Build a test plan: select agents whose surfaces changed, skip the rest, and order the selected
+ * by priority = risk * (1 + matches) + boost (descending). Ties break by ascending agentId for
+ * determinism.
+ */
+export function planTests(changedFiles, descriptors, options) {
+    const selected = [];
+    const skipped = [];
+    for (const descriptor of descriptors) {
+        const matches = matchCount(descriptor, changedFiles);
+        if (matches === 0) {
+            skipped.push(descriptor.agentId);
+            continue;
+        }
+        const boost = options?.boosts?.get(descriptor.agentId) ?? 0;
+        const priority = descriptor.risk * (1 + matches) + boost;
+        selected.push({
+            agentId: descriptor.agentId,
+            name: descriptor.name,
+            priority,
+            reason: `risk ${descriptor.risk} x ${matches} changed surface(s)${boost ? ` + ${boost} blast-radius boost` : ''}`,
+        });
+    }
+    selected.sort((a, b) => (b.priority - a.priority) || (a.agentId - b.agentId));
+    return { changedFiles, selected, skipped };
+}
+//# sourceMappingURL=diff-planner.js.map

package/dist/core/tester/diff-planner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-planner.js","sourceRoot":"","sources":["../../../core/tester/diff-planner.ts"],"names":[],"mappings":"AAaA,oEAAoE;AACpE,SAAS,UAAU,CAAC,UAA2B,EAAE,YAA+B;IAC9E,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,iFAAiF;QACjF,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAAE,KAAK,IAAI,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,YAA+B,EAC/B,WAAuC,EACvC,OAAqB;IAErB,MAAM,QAAQ,GAAuB,EAAE,CAAC;IACxC,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,UAAU,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QACrD,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;YAClB,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YACjC,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5D,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,KAAK,CAAC;QACzD,QAAQ,CAAC,IAAI,CAAC;YACZ,OAAO,EAAE,UAAU,CAAC,OAAO;YAC3B,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,QAAQ;YACR,MAAM,EAAE,QAAQ,UAAU,CAAC,IAAI,MAAM,OAAO,sBAAsB,KAAK,CAAC,CAAC,CAAC,MAAM,KAAK,qBAAqB,CAAC,CAAC,CAAC,EAAE,EAAE;SAClH,CAAC,CAAC;IACL,CAAC;IAED,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9E,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC7C,CAAC"}

package/dist/core/tester/honest-report.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Honest reporting (Phase 3.1) — #1 never declares green it can't prove, and NEVER ROUNDS UP.
+ * The verdict is conservative by construction: any failure => fail; any skip => partial; any
+ * happy-path-only agent => smoke (not a pass); zero tests => never a pass. Exact counts only.
+ * Spec: blueprint/agents/01-testteam-bot.md ("Visible + honest; never rounds up").
+ */
+import type { AgentResultSummary, HonestReport } from './types.js';
+/**
+ * Build an honest report. Verdict precedence (most to least severe), so green is never overstated:
+ *   fail (any failed) > partial (any skipped, or zero tests) > smoke (any happy-path-only) > pass.
+ */
+export declare function buildHonestReport(results: readonly AgentResultSummary[]): HonestReport;
+//# sourceMappingURL=honest-report.d.ts.map

package/dist/core/tester/honest-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"honest-report.d.ts","sourceRoot":"","sources":["../../../core/tester/honest-report.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAyB,MAAM,SAAS,CAAC;AAkBvF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,YAAY,CAwCtF"}

package/dist/core/tester/honest-report.js

@@ -0,0 +1,64 @@
+const isValidCount = (n) => Number.isFinite(n) && n >= 0;
+function sumTotals(results) {
+    let passed = 0;
+    let failed = 0;
+    let skipped = 0;
+    let valid = true;
+    for (const r of results) {
+        if (!isValidCount(r.passed) || !isValidCount(r.failed) || !isValidCount(r.skipped))
+            valid = false;
+        passed += isValidCount(r.passed) ? Math.floor(r.passed) : 0;
+        failed += isValidCount(r.failed) ? Math.floor(r.failed) : 0;
+        skipped += isValidCount(r.skipped) ? Math.floor(r.skipped) : 0;
+    }
+    return { totals: { total: passed + failed + skipped, passed, failed, skipped }, valid };
+}
+/**
+ * Build an honest report. Verdict precedence (most to least severe), so green is never overstated:
+ *   fail (any failed) > partial (any skipped, or zero tests) > smoke (any happy-path-only) > pass.
+ */
+export function buildHonestReport(results) {
+    const { totals, valid } = sumTotals(results);
+    const caveats = [];
+    // A productive run can still hide a SILENT agent (0/0/0) — crashed, timed out, or never invoked.
+    // The aggregate total masks it; surface it per-agent so green is never overstated.
+    const silentAgents = valid ? results.filter((r) => r.passed + r.failed + r.skipped === 0) : [];
+    let verdict;
+    if (!valid) {
+        // Uncertifiable input (NaN/negative counts) — fail closed; green must never be overstated.
+        verdict = 'fail';
+        caveats.push('invalid test counts (NaN/negative) — cannot certify; failing closed');
+    }
+    else if (totals.total === 0) {
+        verdict = 'partial';
+        caveats.push('0 tests executed — not a pass');
+    }
+    else if (totals.failed > 0) {
+        verdict = 'fail';
+        caveats.push(`${totals.failed} failing test(s) — not green`);
+    }
+    else if (totals.skipped > 0) {
+        verdict = 'partial';
+        caveats.push(`${totals.skipped} skipped test(s) — cannot claim all-pass`);
+    }
+    else if (silentAgents.length > 0) {
+        verdict = 'partial'; // a silent agent among productive ones — not a clean pass
+    }
+    else if (results.some((r) => r.happyPathOnly)) {
+        verdict = 'smoke';
+        caveats.push('happy-path-only coverage — smoke pass, not a full pass');
+    }
+    else {
+        verdict = 'pass';
+    }
+    for (const r of silentAgents) {
+        caveats.push(`agent ${r.agentId} (${r.name}) executed 0 tests — not a pass`);
+    }
+    const missingEvidence = results.filter((r) => r.failed > 0 && (!r.evidence || r.evidence.length === 0));
+    for (const r of missingEvidence) {
+        caveats.push(`agent ${r.agentId} (${r.name}) reported failures without evidence`);
+    }
+    const summary = `${totals.passed} of ${totals.total} passed, ${totals.failed} failed, ${totals.skipped} skipped`;
+    return { totals, verdict, summary, perAgent: results, caveats };
+}
+//# sourceMappingURL=honest-report.js.map

package/dist/core/tester/honest-report.js.map

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

package/dist/core/tester/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Agent #1 "The Tester" — conductor core (Phase 3.1).
+ * Diff-aware, risk-based planning + honest (never-rounds-up) reporting.
+ * Spec: blueprint/agents/01-testteam-bot.md.
+ */
+export type { AgentDescriptor, PrioritizedAgent, TestPlan, AgentResultSummary, Verdict, ReportTotals, HonestReport, } from './types.js';
+export { planTests, type PlanOptions } from './diff-planner.js';
+export { buildHonestReport } from './honest-report.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/tester/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../core/tester/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,kBAAkB,EAClB,OAAO,EACP,YAAY,EACZ,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/core/tester/index.js

@@ -0,0 +1,3 @@
+export { planTests } from './diff-planner.js';
+export { buildHonestReport } from './honest-report.js';
+//# sourceMappingURL=index.js.map

package/dist/core/tester/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../core/tester/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,SAAS,EAAoB,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/core/tester/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Agent #1 "The Tester" — conductor of the 84-engine — shared types (Phase 3.1).
+ * #1 drives the engine: it tests only what changed (diff-aware), runs the highest-risk surfaces
+ * first (risk-based prioritization), and reports HONESTLY — N of M, X/Y/Z, never rounding up.
+ * Spec: blueprint/agents/01-testteam-bot.md.
+ */
+/** A description of an engine sub-agent #1 conducts, and the surfaces it owns. */
+export interface AgentDescriptor {
+    readonly agentId: number;
+    readonly name: string;
+    /** Path fragments this agent is responsible for (substring match against changed files). */
+    readonly surfaces: readonly string[];
+    /** Base risk weight (higher = more critical). */
+    readonly risk: number;
+}
+export interface PrioritizedAgent {
+    readonly agentId: number;
+    readonly name: string;
+    readonly priority: number;
+    readonly reason: string;
+}
+export interface TestPlan {
+    readonly changedFiles: readonly string[];
+    /** Agents to run, highest-priority first. */
+    readonly selected: readonly PrioritizedAgent[];
+    /** Agents whose surfaces did not change — skipped (diff-aware). */
+    readonly skipped: readonly number[];
+}
+/** Per-agent result rolled up by #1. */
+export interface AgentResultSummary {
+    readonly agentId: number;
+    readonly name: string;
+    readonly passed: number;
+    readonly failed: number;
+    readonly skipped: number;
+    /** Happy-path-only is a SMOKE test, not a pass (spec #6). */
+    readonly happyPathOnly?: boolean;
+    readonly evidence?: readonly string[];
+}
+export type Verdict = 'pass' | 'fail' | 'partial' | 'smoke';
+export interface ReportTotals {
+    readonly total: number;
+    readonly passed: number;
+    readonly failed: number;
+    readonly skipped: number;
+}
+export interface HonestReport {
+    readonly totals: ReportTotals;
+    readonly verdict: Verdict;
+    /** Exact, never-rounded one-liner. */
+    readonly summary: string;
+    readonly perAgent: readonly AgentResultSummary[];
+    readonly caveats: readonly string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/tester/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../core/tester/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC"}

package/dist/core/tester/types.js

@@ -0,0 +1,8 @@
+/**
+ * Agent #1 "The Tester" — conductor of the 84-engine — shared types (Phase 3.1).
+ * #1 drives the engine: it tests only what changed (diff-aware), runs the highest-risk surfaces
+ * first (risk-based prioritization), and reports HONESTLY — N of M, X/Y/Z, never rounding up.
+ * Spec: blueprint/agents/01-testteam-bot.md.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/tester/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../core/tester/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/core/triggers/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Trigger Management System (#27) MVP — public surface (Phase 2.2).
+ * Push bus with coalescing, priority, load-shedding, loop-detection, freeze, and fail-safe.
+ * Spec: blueprint/agents/27-trigger-management-system.md.
+ */
+export type { TriggerType, Priority, TriggerEvent, ProvenanceLink, Activation, DropRecord, TriggerConfig, } from './types.js';
+export { DEFAULT_TRIGGER_CONFIG } from './types.js';
+export { TriggerBus } from './trigger-bus.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/triggers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../core/triggers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EACV,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,UAAU,EACV,UAAU,EACV,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/core/triggers/index.js

@@ -0,0 +1,3 @@
+export { DEFAULT_TRIGGER_CONFIG } from './types.js';
+export { TriggerBus } from './trigger-bus.js';
+//# sourceMappingURL=index.js.map

package/dist/core/triggers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../core/triggers/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/core/triggers/trigger-bus.d.ts

@@ -0,0 +1,49 @@
+/**
+ * TriggerBus (#27 MVP, Phase 2.2) — an in-process push bus that coalesces bursts, prioritizes,
+ * load-sheds under overload, detects self-re-triggering loops (circuit-breaker), honors a global
+ * freeze (ties the Harness actuation-freeze), and FAILS SAFE when degraded (never fires risky
+ * actuation). Every activation carries a provenance chain. Spec: blueprint/agents/27-*.md.
+ *
+ * Boundary with #26: this layer is reactive event-routing only — it signals; it never acts.
+ */
+import { type Activation, type DropRecord, type TriggerConfig, type TriggerEvent } from './types.js';
+export declare class TriggerBus {
+    private readonly subscribers;
+    private readonly buffer;
+    private readonly fireTimes;
+    private readonly tripped;
+    private readonly fired;
+    private readonly dropped;
+    private readonly config;
+    private readonly now;
+    private frozen;
+    private available;
+    constructor(config?: Partial<TriggerConfig>, options?: {
+        readonly clock?: () => number;
+    });
+    /** Wake `agentId` directly (decentralized-first — survives even if #26 is down). */
+    subscribe(agentId: number, handler: (activation: Activation) => void): void;
+    freeze(): void;
+    unfreeze(): void;
+    get isFrozen(): boolean;
+    /** Degrade the bus (e.g. overwhelmed) — fail-safe blocks all firing. */
+    setAvailable(value: boolean): void;
+    get auditTrail(): readonly Activation[];
+    get dropLog(): readonly DropRecord[];
+    get bufferedKeys(): number;
+    isCircuitBroken(agentId: number): boolean;
+    /** Queue an event. Identical idempotency keys within the window coalesce into one activation. */
+    submit(event: TriggerEvent): void;
+    private coalesceKey;
+    /**
+     * Deliver coalesced activations whose window has elapsed (or all, when `force`). Critical first;
+     * under overload low/normal are shed; looping agents are circuit-broken; degraded fails safe.
+     */
+    flush(force?: boolean): readonly Activation[];
+    private isLooping;
+    private fire;
+    private drop;
+    /** Bound an audit array to maxAuditEntries (keep the most recent) — bounded memory under load. */
+    private cap;
+}
+//# sourceMappingURL=trigger-bus.d.ts.map

package/dist/core/triggers/trigger-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger-bus.d.ts","sourceRoot":"","sources":["../../../core/triggers/trigger-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,UAAU,EAGf,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,SAAS,CAAC;AAWjB,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuD;IACnF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAQ;gBAEb,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;KAAE;IAKxF,oFAAoF;IACpF,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI;IAI3E,MAAM,IAAI,IAAI;IAGd,QAAQ,IAAI,IAAI;IAGhB,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,wEAAwE;IACxE,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAIlC,IAAI,UAAU,IAAI,SAAS,UAAU,EAAE,CAEtC;IACD,IAAI,OAAO,IAAI,SAAS,UAAU,EAAE,CAEnC;IACD,IAAI,YAAY,IAAI,MAAM,CAEzB;IACD,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIzC,iGAAiG;IACjG,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAwBjC,OAAO,CAAC,WAAW;IAInB;;;OAGG;IACH,KAAK,CAAC,KAAK,UAAQ,GAAG,SAAS,UAAU,EAAE;IA2C3C,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,IAAI;IAyBZ,OAAO,CAAC,IAAI;IAKZ,kGAAkG;IAClG,OAAO,CAAC,GAAG;CAIZ"}