diff --git a/README.md b/README.md index 7c4d63b..3bb4994 100644 --- a/README.md +++ b/README.md @@ -34,5 +34,9 @@ console crash on the Russian-locale Windows target. | boundary + STS runner + artifacts + lift-out home | `OwnAudit/` (this repo) | active | | fix arm — wire mass appliers + safety wrapper + OWN fixer | `OwnAudit/` ([docs/fix-arm.md](docs/fix-arm.md)) | design | | LeakFixMine — mine real leak-fixes, SZZ-prove them, score OwnAudit vs baselines | `leakmine/` ([docs/leakfix-mine.md](docs/leakfix-mine.md)) | active | +| agent-run triage — ingest 007's Zero Trust audit trail as evidence | `OwnAudit/` ([docs/agent-run-triage.md](docs/agent-run-triage.md)) | design | +| architecture review — drift gate & report pipeline over Own.Arch facts | `OwnAudit/` ([docs/architecture-review.md](docs/architecture-review.md)) | design | +| sketch-based evidence layer — compact cross-run finding summaries | `OwnAudit/` ([docs/sketch-based-evidence.md](docs/sketch-based-evidence.md)) | design | +| agentic coding discipline — task contracts, diff gates, judge-run | `OwnAudit/` ([docs/agentic-coding-discipline-proposal.md](docs/agentic-coding-discipline-proposal.md)) | design | See [PLAN.md](PLAN.md), the [Fix arm design](docs/fix-arm.md), and [LeakFixMine](docs/leakfix-mine.md). diff --git a/docs/agent-run-triage.md b/docs/agent-run-triage.md new file mode 100644 index 0000000..826a495 --- /dev/null +++ b/docs/agent-run-triage.md @@ -0,0 +1,154 @@ +# Agent-run triage — 007's Zero Trust audit trail as an evidence source + +Status: design note / vision, not implementation (same status as +[`audit-data-leverage.md`](audit-data-leverage.md) and +[`own-net-auditor.md`](own-net-auditor.md)). Trigger to build: once **007** +actually emits structured per-run capability events (its Phase 1 — see +`007/docs/zero-trust-framework.md`). +Gated on that repo's data existing, not something to build ahead of it. + +## 0. What this is + +007 is a private harness that drives `claude`/`codex` over Own.NET and OwnAudit +via their CLIs, in a throwaway `git worktree`, gated by `.007/gate.toml`. Its own +ADR (`007/docs/security-layers.md`) is honest that the worktree is not a +sandbox and gate steps are attacker-controlled code execution if the target +repo isn't fully trusted. 007's Zero Trust roadmap closes that gap in phases — +Sandboy isolation, a capability manifest, structured audit events. The last +phase in that roadmap is: **something has to look at the resulting evidence and +decide what's noise vs. a real incident.** That's this repo's job, not 007's — +007 orchestrates and enforces; it isn't built to triage its own findings, same +reason OwnAudit doesn't run its own detectors (see +`Own.NET docs/proposals/P-024-security-audit-profile.md` +in Own.NET: "оркестратор, не анализатор" applies here verbatim). + +## 1. Reuse, don't build a new pipeline + +OwnAudit already has the exact shape this needs, built for a different evidence +source: + +- **The confirmed / static-only / runtime-only triage** in + [`runtime-contract.md`](runtime-contract.md) — a static finding plus + independent corroborating evidence (heap retention) becomes `confirmed`; a + finding with no corroboration is a suspect false positive; corroboration with + no matching finding is the analyzer's **blind spot**. The same three buckets + apply directly to policy events: a capability violation that the manifest + intended to catch and did → `confirmed`; a violation rule that never fires → + candidate for retirement; an agent action that *succeeded* but matched no rule + at all → **policy gap** (the blind spot — a candidate for a new rule, exactly + like "runtime-only" means "the static analyzer's blind spot" today). +- **The rule → verdict methodology** in + [`audit-data-leverage.md`](audit-data-leverage.md) — findings are concentrated + (top-N rules dominate volume), so characterizing a handful of rules + characterizes most of the backlog. The same applies to gate/policy rules: a + network-deny rule that fires on every run because a common tool phones home + for a version check is noise to tune, not a real incident every time. + +Nothing here is a new detection engine. It's the same normalize → aggregate → +score → report pipeline, fed a new evidence source. + +## 2. What gets ingested + +From a 007 run record (`runs///`): `meta.json` (run identity — +today `run_id`, `target`, `repo`, `base_commit`, `engine`; the full +`run_id`/`agent_id`/`target_repo`/`base_commit`/`policy_id` identity is itself +a Phase 1 item), `gate/*.log` + +`gate/verdict.json` (per-step pass/fail), and — once Phase 1 lands — capability +manifest violations (attempted network egress under `network = "deny"`, a write +outside the declared scope, an unrecognized `[permissions]` field that failed +closed) and output-filter hits (a secret pattern caught before it reached +`agent.stdout`/`diff.patch`). + +**Before trusting any of it, verify provenance.** 007's records are meant to be +hash-chained (`prev_record_hash`/`record_hash` over the gate manifest, each +step's sandbox policy, the task, the diff, and stdout — see +`007/docs/zero-trust-framework.md` §5). The ingest adapter's first move is +checking that chain, the same reflex `runtime.json`'s consumer already applies +to its own inputs: a broken chain (or a hash that doesn't match the artifact it +claims to describe) is itself the finding — `provenance-broken`, filed +alongside the buckets below, not silently trusted because the JSON parsed. + +Concrete instances of the `policy-violation-confirmed` bucket worth naming, so +"triage" doesn't stay abstract: a step whose policy declares `tcp_connect = []` +shows a denied connect attempt anyway (the boundary caught something — log it, +it's not automatically an incident); a step writes outside its declared `fs_rw` +scope and gets denied; the diff touches `.007/policies/**` without the task +naming a policy change; the diff touches `.007/gate.toml` itself — that last one +is `policy-violation-allowed-then-flagged` even when the gate step technically +passed, because an agent editing its own leash is the one action this pipeline +should never wave through unread. + +This is **not** source-code SARIF — there's no file/line to point at, the +"finding" is about a process's behavior during a run, not a static code +location. It needs its own thin record shape and its own adapter into the +existing aggregation, parallel to how `zap_to_sarif` / `dotnet_vuln_to_sarif` +adapt non-native tool output in the security profile (P-024 in Own.NET) — not a +new report pipeline, a new adapter feeding the one that exists. + +```jsonc +// illustrative — the shape 007 would emit, the adapter's input +{ + "schema": "o7/audit-event/v1", + "run_id": "…", + "agent_id": "claude", + "target_repo": "Own.NET", + "policy_id": "own-net.cue#", + "events": [ + { + "kind": "policy-violation", + "rule": "network.default", + "action": "connect example.com:443", + "step": "regression", + "outcome": "denied" + } + ] +} +``` + +## 3. Triage buckets + +| Bucket | Meaning | Action | +|---|---|---| +| `policy-violation-confirmed` | an action tripped a capability-manifest rule and was denied | evidence of the boundary working — log, don't page | +| `policy-violation-allowed-then-flagged` | an action matched a rule marked `requires_approval` and proceeded | the actual triage queue — did a human actually approve it, or did it slip through | +| `policy-gap` | an action succeeded, matched no rule at all | the manifest's blind spot — candidate for a new rule, same lens as "runtime-only" in `runtime-contract.md` | +| `suppressed-noise` | a rule fires on nearly every run for a benign reason (e.g. a toolchain's version-check phones home) | tune the rule, don't keep flagging it — same rule→verdict lens as `audit-data-leverage.md` | + +## 4. Non-goals + +- **Not enforcement.** OwnAudit never blocks or allows an agent action — that + authority stays at 007 + Sandboy, at the process boundary, before the action + happens. This repo only ever looks at what already happened. +- **Not disposition.** Per the Zero Trust framework this whole effort traces + back to: agents can automate evidence collection, enrichment, and drafting an + incident note; containment, rerun, and escalation decisions stay a human + call. A `policy-violation-allowed-then-flagged` event becomes a note a person + reads, not an automatic rerun/block. +- **Not a new detector engine.** Same charter as P-024 in Own.NET: no bespoke + heuristics, no own severity model reinvented from scratch — reuse the + cross-tool-agreement scorer and the coverage-map discipline (`NO-TOOL: + skipped` beats a guess) that already exist for static and runtime findings. + +## 5. Cross-repo division of responsibility (this repo's view) + +| Concern | Owner | +|---|---| +| Declares/verifies the capability vocabulary (`owen.policy`, authored in CUE) | Own.NET — `docs/notes/agent-capability-layer.md` | +| Process/syscall isolation boundary | Own.NET — `sandboy/` | +| Enforces policy at runtime, emits the structured audit trail | 007 — `docs/zero-trust-framework.md` | +| Ingests the trail, triages, reports, keeps disposition human | **OwnAudit** — this doc | + +## 6. Where this lands + +Layout, if/when 007 Phase 1 lands and this gets built: + +```text +audit/agent-runs/ # parallel to the audit/security/ layout proposed + # in Own.NET P-024 (not yet built) + adapters/ # o7_run_to_finding.py + profiles/ # which run stores to poll, retention window +``` + +Consistent with the existing lift-out discipline (`PLAN.md`): the pipeline +logic belongs wherever the rest of `audit/aggregate` lives at build time, and +this repo carries the boundary + validated runs, same as everything else here. diff --git a/docs/agentic-coding-discipline-proposal.md b/docs/agentic-coding-discipline-proposal.md new file mode 100644 index 0000000..6c59f45 --- /dev/null +++ b/docs/agentic-coding-discipline-proposal.md @@ -0,0 +1,13 @@ +# Agentic Coding Discipline — Proposal (pointer) + +> Статус: **pointer**. Канонический текст этого предложения (task contracts, +> negative prompts, plan-then-build, diff policy gates, judge-run, trust levels +> — для Own.NET/OwnAudit/007) живёт в публичном репо Own.NET: +> `Own.NET/docs/agentic-coding-discipline-proposal.md` +> (https://github.com/PhysShell/Own.NET/blob/main/docs/agentic-coding-discipline-proposal.md). +> +> Раньше идентичная копия лежала в каждом из трёх репозиториев; копии +> неизбежно расходятся, поэтому здесь оставлен только указатель. + +Что из этого предложения уже опирается на OwnAudit: `docs/fp-judge/verdict-contract.md` +и `docs/fp-judge/rubric.md` — источник истины, под который подстроена judge-схема 007. diff --git a/docs/architecture-review.md b/docs/architecture-review.md new file mode 100644 index 0000000..f8f368a --- /dev/null +++ b/docs/architecture-review.md @@ -0,0 +1,411 @@ +# OwnAudit architecture review, drift gate & report pipeline + +- **Status:** draft. Imported from a design discussion and normalized. + +## Summary + +Introduce an OwnAudit-side architecture review pipeline that consumes architecture facts from Own.NET, applies reporting/baseline/drift logic, and emits PR-friendly architecture reports, SARIF, and gate verdicts. + +OwnAudit should not own the extractor or analyzer core. That belongs in Own.NET. OwnAudit owns: + +- consuming `arch-facts.json` and `arch-findings.json`; +- baseline and diff for architecture findings; +- architecture drift snapshots; +- PR markdown reports; +- SARIF export; +- dashboard integration; +- risk scoring; +- report-only high-level review summaries. + +This proposal turns the existing "arch/" work into a product-shaped pipeline. + +## Existing groundwork + +OwnAudit already has an architecture roadmap that positions the project as an auditor built from semantic code graph, architecture rules, WPF/runtime probes, baseline/diff, SARIF/GitHub reports, and an AI explanation layer. + +The roadmap explicitly says this is not a greenfield rewrite: OwnAudit already has findings, CLI orchestration, baseline/diff concepts, graph/dashboard artifacts, history, tiers, gates, and local smells; the real gap is cross-cutting architecture rules. + +OwnAudit already contains "arch/drift.py", which compares structure between graph snapshots and reports coupling movement, new dependency edges, and newly introduced cycles before those necessarily become hard rule violations. + +OwnAudit already has "arch/rules.json" with concrete architecture rules: UI reaching SQL/data layer, Domain depending on WPF/presentation framework, cycle detection, god-class thresholds, coupling rules, and drift-sensitive targets such as SQL/WPF/DevExpress. + +The roadmap also documents Phase 3 as an architecture pass over Roslyn-generated "graph.json", with Python-side evaluation producing findings in the same "findings.json" schema for SARIF/diff/dashboard reuse. + +Related docs: + +- [agentic-coding-discipline-proposal.md](agentic-coding-discipline-proposal.md) + This doc adds a design note on disciplined agentic coding, task contracts, negative prompts, plan-then-build, diff policy gates, judge-run, and trust levels for Own.NET/OwnAudit/007. + +- 007 `docs/agentic-coding-discipline-proposal.md` + This is relevant because it records the 007-side isolate → run → gate → harvest loop and future task/diff-policy gates that OwnAudit can depend on instead of reinventing agent execution. + +## Problem + +OwnAudit has the right pieces, but architecture review is currently split across: + +- rules; +- drift diff; +- baseline/diff; +- graph docs; +- dashboard generation; +- future SARIF/reporting integration. + +The missing product slice is a single command that answers: + +What architectural debt exists? +What changed in this PR? +What is newly blocking? +What is old/baselined? +What is high-risk but report-only? +What should a reviewer look at first? + +Without this, developers still need to read raw JSON or multiple partial reports. That is how useful analysis dies: not because the detector is wrong, but because the output is a filing cabinet thrown down a staircase. + +## Proposed command surface + +Add: + +```bash +python3 -m arch.review_cli \ + --facts arch-facts.json \ + --findings arch-findings.json \ + --rules arch/rules.json \ + --baseline architecture-baseline.json \ + --drift-baseline arch-snapshot.main.json \ + --out-dir arch/out \ + --gate-level error +``` + +Outputs: + +```text +arch/out/ + architecture-review.md + architecture-findings.sarif + architecture-findings.json + architecture-drift.json + architecture-drift.md + architecture-verdict.json + architecture-summary.json +``` + +## Pipeline + +```text +Own.NET arch facts/findings + ↓ +OwnAudit normalization + ↓ +baseline/diff + ↓ +drift snapshot comparison + ↓ +risk scoring + ↓ +SARIF + markdown + dashboard artifacts + ↓ +gate verdict +``` + +## Inputs + +### `arch-facts.json` + +Produced by Own.NET. + +Contains project/type/component dependency graph. + +### `arch-findings.json` + +Produced by Own.NET `Own.Arch` (see `Own.NET docs/proposals/P-032-own-arch-facts.md`). + +Contains deterministic architecture findings with fingerprints. + +### `architecture-baseline.json` + +OwnAudit-owned artifact for accepted historical findings. + +Purpose: + +- allow adoption in dirty legacy codebases; +- fail only on new violations; +- force explicit reason when accepting new debt. + +### `arch-snapshot.main.json` + +OwnAudit-owned drift snapshot. + +Used to compare current PR structure against main. + +The existing drift design already treats snapshots as compact summaries containing component metrics, dependency surface, and cycles. + +## Report model + +The architecture review report should have five sections. + +1. Verdict + +```text +FAIL: 2 new blocking architecture violations. +WARN: 3 medium-risk drift items. +INFO: 1 dependency removed. +``` + +2. New blocking findings + +Only findings that are: + +- deterministic; +- not present in baseline; +- severity at or above gate level. + +Example: + +```text +ARCH001: Presentation depends on Infrastructure directly +Evidence: + Broker.Presentation -> Broker.Infrastructure + source: Broker.Presentation.csproj ProjectReference + +Why this matters: + Presentation can bypass Application policies and reach persistence implementation directly. +``` + +3. Baselined debt + +Existing violations remain visible but do not block. + +Example: + +```text +ARCH-DOMAIN-WPF: 7 existing findings +Baseline reason: + legacy ViewModel formatting leaked into Domain; tracked separately +``` + +4. Drift since main + +Use existing "arch.drift" concepts: + +- new dependency; +- removed dependency; +- new cycle; +- resolved cycle; +- coupling increase; +- instability shift. + +Example: + +```text +High: new dependency Sts.Domain.Orders -> System.Data.SqlClient +Medium: Sts.UI.ViewModels Ce 21 -> 27 (+6, +29%) +Info: removed dependency Sts.Legacy.Import -> DevExpress.Xpf +``` + +5. Recommended reviewer focus + +This section is report-only and may be generated from deterministic evidence. + +Example: + +```text +Reviewer focus: +1. The PR introduces a new Domain -> SQL dependency. +2. The PR increases UI ViewModel outgoing dependencies by 29%. +3. No new cycles were introduced. +``` + +## Gate policy + +Default gate behavior: + +error: fail on new deterministic architecture findings +high drift: fail only if configured +medium drift: report-only by default +heuristics: report-only by default +LLM review text: never gates directly + +Example: + +```json +{ + "schema": "own.audit.arch.verdict/v1", + "verdict": "fail", + "blocking": [ + { + "kind": "finding", + "rule": "ARCH001", + "fingerprint": "sha256:..." + } + ], + "nonBlocking": [ + { + "kind": "drift", + "risk": "medium", + "detail": "Sts.UI.ViewModels Ce 21 -> 27" + } + ] +} +``` + +## SARIF export + +OwnAudit should convert architecture findings to SARIF with: + +- rule id; +- severity; +- fingerprint; +- source evidence; +- help text; +- baseline status if available. + +Only deterministic findings should become code scanning alerts by default. + +Drift items can be added as SARIF notes later, but they should start as markdown/report artifacts. Drift often describes component-level movement rather than a single source span. + +## AI explanation layer + +The AI layer must be downstream of deterministic results. + +Allowed AI tasks: + +- summarize top architecture risks; +- explain why a rule matters; +- group repeated violations by root cause; +- propose refactoring steps; +- produce PR review text; +- suggest candidate 007 tasks. + +Forbidden AI tasks: + +- invent new blocking findings without analyzer evidence; +- change gate verdict; +- update baseline automatically; +- suppress architecture findings without explicit reason; +- treat style inference as deterministic truth. + +## Example report + +```markdown +# Architecture Review + +Verdict: FAIL + +## Blocking new violations + +### ARCH001: Presentation depends on Infrastructure + +Evidence: +- `Broker.Presentation` -> `Broker.Infrastructure` +- source: `Broker.Presentation.csproj` + +Impact: +Presentation can bypass Application and directly depend on persistence implementation. + +Suggested refactor: +Introduce an Application service or port and move the concrete Infrastructure dependency behind it. + +## Drift since main + +- High: new dependency `Sts.Domain.Orders` -> `System.Data.SqlClient` +- Medium: `Sts.UI.ViewModels` efferent coupling `21 -> 27` +- Info: removed dependency `Sts.Legacy.Import` -> `DevExpress.Xpf` + +## Baselined debt + +- 7 existing `ARCH-DOMAIN-WPF` findings remain unchanged. +``` + +## Dashboard integration + +Extend existing dashboard artifacts with an Architecture tab: + +```text +Architecture + - verdict + - new blocking findings + - total baselined debt + - drift count by risk + - top risky components by Ce growth + - cycles introduced/resolved +``` + +No new dashboard model should be invented if existing "viz/" history/report artifacts can be reused. + +## Integration with 007 + +OwnAudit should emit machine-readable candidate tasks for 007. + +Example: + +```json +{ + "schema": "own.audit.arch.task-candidates/v1", + "tasks": [ + { + "task_id": "ownarch.fix.arch001.presentation-infrastructure", + "finding_rule": "ARCH001", + "finding_fingerprint": "sha256:...", + "recommended_prompt_module": "ownarch.fix-layer-violation", + "risk": "high", + "constraints": { + "max_files_changed": 5, + "require_reaudit": true, + "forbid_baseline_update": true + } + } + ] +} +``` + +007 remains responsible for executing/refactoring. OwnAudit only prepares evidence and gates. + +## Acceptance criteria + +MVP is accepted when: + +1. "arch.review_cli" consumes "arch-findings.json", optional baseline, and optional drift snapshot. +2. It emits "architecture-review.md". +3. It emits "architecture-verdict.json". +4. It can fail with exit code "2" on new blocking deterministic architecture findings. +5. It can run in report-only mode. +6. It integrates with existing baseline/diff conventions. +7. It reuses existing "arch/drift.py" output instead of duplicating drift logic. +8. It emits SARIF for deterministic architecture findings. +9. Tests cover: + - clean architecture report; + - new blocking finding; + - baselined finding; + - new high-risk drift; + - report-only medium drift; + - no baseline file; + - malformed facts/findings input. + +## Risks + +Risk: architecture review becomes generic lint soup + +Mitigation: only include findings with architectural evidence. Complexity, dead code, coverage, and formatting belong elsewhere. + +Risk: drift becomes noisy + +Mitigation: drift gates are opt-in and thresholded. Default is report-only except for high-risk sensitive-target dependencies. + +Risk: AI summary overclaims + +Mitigation: every AI-generated claim must cite a deterministic finding, drift item, or metric. No evidence, no claim. + +## First implementation slice + +Implement: + +```text +arch/review_cli.py +arch/report.py +architecture-review.md renderer +architecture-verdict.json +SARIF export for deterministic arch findings +tests +``` + +Do not implement LLM review in the first slice. First make the boring pipeline work. Then let the parrot narrate the evidence. \ No newline at end of file diff --git a/docs/sketch-based-evidence.md b/docs/sketch-based-evidence.md new file mode 100644 index 0000000..2fee52d --- /dev/null +++ b/docs/sketch-based-evidence.md @@ -0,0 +1,296 @@ +# Sketch-based evidence layer for architecture and code audit + +- **Status:** draft. Imported from a design discussion and normalized; the + pasted original suggested an Own.NET-style `P-NNN` path, but OwnAudit keeps + flat topic docs under `docs/`. +- **Related:** `007 docs/sketch-aware-evidence.md` (the 007-side per-run + execution evidence this layer ingests) and + `Own.NET docs/proposals/P-033-probabilistic-data-structures.md` (the + in-process instrumentation whose `own.sketches.v1` exports this layer + anticipates). + +## Summary + +OwnAudit should add a sketch-based evidence layer for compactly summarizing audit findings across repositories, pull requests, builds, and analyzer outputs. + +The goal is to make OwnAudit better at answering questions such as: + +- which files are repeatedly risky; +- which rules fire most often; +- which warnings are noise; +- which modules have unstable ownership; +- which tests are slow or flaky; +- which PRs have unusually large blast radius; +- which findings are duplicates under different wording; +- which architecture drift signals are increasing over time. + +This proposal complements the existing direction where OwnAudit acts as an evidence orchestrator and audit/report/gate layer. Own.NET can produce facts. 007 can produce agent execution evidence. OwnAudit should aggregate, rank, compare, and explain. + +## Problem + +Architecture audits often drown in raw findings: + +```text +312 warnings +48 changed files +9 analyzer categories +17 test failures +5 architecture rules +2 flaky checks +1 very tired developer +``` + +Raw counts are not enough. They do not explain trend, severity, repetition, blast radius, or whether the same issue keeps coming back wearing a fake mustache. + +OwnAudit needs compact evidence models that can survive repeated runs and answer: + +- what changed since the last audit; +- what is newly risky; +- what is chronically risky; +- what is statistically abnormal; +- what should block a gate; +- what should merely be reported; +- what should be suppressed as known noise. + +## Proposed solution + +Introduce a normalized evidence layer, `OwnAudit.Evidence.Sketches`. + +It should support the following families of summaries. + +### 1. Heavy hitters for repeated risk + +Use Top-K / Space-Saving style summaries for: + +- files most often changed; +- files most often involved in failed checks; +- rules most often triggered; +- symbols most often touched by refactors; +- modules most often violating architecture boundaries; +- tests most often flaky; +- dependencies most often involved in policy violations. + +Example output: + +```json +{ + "schema": "ownaudit.heavy_hitters.v1", + "kind": "rule_findings_by_file", + "top": [ + { + "key": "src/Foo/Bar.cs", + "estimatedCount": 31, + "lastSeenRunId": "2026-07-06T12-00-00Z" + } + ] +} +``` + +### 2. Latency sketches for CI and analyzer timing + +Use t-digest/DDSketch-like summaries for: + +- analyzer execution time; +- build step duration; +- test duration; +- PR audit duration; +- report generation duration. + +This lets OwnAudit report: + +```text +Analyzer OWN014: + p50: 180 ms + p95: 2.1 s + p99: 5.8 s +``` + +This matters because “the analyzer is fast on average” is how slow tools sneak into CI and start eating morale. + +### 3. Bitmap indexes for audit slicing + +Use bitmap or roaring-style indexes to represent sets of internal ids: + +- files affected by rule X; +- files changed in PR Y; +- files owned by module Z; +- files violating architecture boundary B; +- tests covering changed files; +- findings suppressed by policy; +- findings promoted to gate failures. + +Then OwnAudit can compute: + +```text +GateFailures = + ChangedFiles + AND ArchitectureViolations + AND NOT SuppressedFindings +``` + +This gives OwnAudit a compact internal query model for reports and gates. + +### 4. SimHash / MinHash for finding duplicates and near-duplicates + +Use fingerprints for: + +- similar analyzer findings; +- repeated review comments; +- similar stack traces; +- near-duplicate architecture drift explanations; +- repeated agent mistakes from 007 (the per-run fingerprints arrive via the + export defined in `007 docs/sketch-aware-evidence.md`); +- copy-pasted code smells. + +The output should group related findings: + +```json +{ + "schema": "ownaudit.similar_findings.v1", + "groupId": "simhash:8f31...", + "items": [ + "OWN014 in FileA.cs", + "OWN014 in FileB.cs" + ], + "reason": "similar diagnostic message and nearby code structure" +} +``` + +### 5. Optional HLL for unique cardinality trends + +Use HLL/HLL++ style sketches only where exact distinct counting is too expensive or noisy: + +- unique files touched over time; +- unique rules triggered; +- unique symbols affected; +- unique contributors touching risky modules; +- unique dependency packages observed. + +For most small repositories, exact sets are enough. HLL should not be added just to look sophisticated. That would be technical debt wearing a lab coat. + +## Architecture + +OwnAudit should treat sketches as evidence, not as final truth. + +Suggested flow: + +```text +raw inputs + -> parsers + -> normalized facts + -> sketch aggregators + -> audit evidence + -> policy/gate + -> report +``` + +Inputs may include: + +- Own.NET analyzer facts; +- build logs; +- test results; +- Git diff metadata; +- architecture rules; +- 007 action plans and effect ledgers; +- previous OwnAudit reports. + +Outputs should be stable JSON artifacts: + +```text +artifacts/ownaudit/evidence/ + heavy-hitters.json + latency-sketches.json + bitmap-indexes.json + similarity-groups.json + trend-summary.json +``` + +## Policy integration + +Sketch evidence should support policies such as: + +```yaml +rules: + - id: audit.hotspot.file_changed_too_often + when: + heavy_hitter: + kind: changed_files + min_estimated_count: 10 + severity: warning + + - id: audit.pr.large_architecture_blast_radius + when: + bitmap_intersection: + left: changed_files + right: architecture_sensitive_files + min_count: 5 + severity: error +``` + +The goal is not to make OwnAudit mystical. The goal is to make repeated patterns visible and enforceable. + +## MVP + +The MVP should include: + +1. stable evidence schema; +2. Top-K heavy hitters for: + - files by findings; + - rules by frequency; + - tests by failure count. +3. simple latency summaries for audit/build/analyzer duration; +4. bitmap index abstraction for file ids and finding ids; +5. report section: + - “Repeated hotspots”; + - “New anomalies”; + - “Chronic findings”; + - “Large blast-radius changes”. + +## Phase 2 + +Add: + +- SimHash grouping for similar findings; +- trend comparison across audit runs; +- JSON schema validation; +- gate policy integration; +- ingestion of 007 run evidence; +- ingestion of Own.NET runtime diagnostic exports. + +## Non-goals + +OwnAudit should not: + +- become a time-series database; +- store every raw event forever; +- replace Prometheus/Grafana; +- pretend approximate summaries are exact facts; +- block PRs only because a probabilistic estimate twitched; +- require Redis/Valkey to run local audit. + +Approximate evidence can raise suspicion. Exact evidence should convict. Tiny difference, huge legal and engineering consequences. + +## Acceptance criteria + +This proposal is successful when: + +- OwnAudit can identify repeated file/rule/test hotspots; +- reports show p95/p99 durations, not only averages; +- PR reports can describe blast radius using set intersections; +- similar findings can be grouped instead of repeated as spam; +- gate rules can consume sketch-derived evidence with clear thresholds; +- exported artifacts are stable enough for 007 and Own.NET integration; +- the system remains usable without external infrastructure. + +## Expected benefit + +OwnAudit becomes less of a static report printer and more of an evidence engine: + +- better prioritization; +- clearer architecture drift signals; +- fewer duplicate findings; +- more useful PR gates; +- better historical comparison; +- stronger bridge between Own.NET facts and 007 execution evidence. + +The important part: OwnAudit should not merely say “there are problems”. That is useless; everyone knows there are problems. OwnAudit should say which problems are recurring, growing, risky, and worth fixing now. \ No newline at end of file