edsger 0.83.0 → 0.85.0

package/README.md

@@ -1,7 +1,7 @@
 # edsger
 
-> Agentic CLI to **benchmark** repositories and **review** / **resolve** pull
-> requests against industrial-grade engineering standards.
+> Agentic CLI to **benchmark** and **audit** repositories and **review** /
+> **resolve** pull requests against industrial-grade engineering standards.
 
 `edsger` runs the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)
 over your code. The standards it applies (security, maintainability, testing,
@@ -40,6 +40,36 @@ Every run is archived under `.edsger/benchmark/runs/<timestamp>/` and appended t
 `.edsger/benchmark/history.jsonl`, so the JSON data is committable and the
 dashboard can show history and trends over time.
 
+### `edsger audit` — nitpick the whole repo
+
+Comb through the repository hunting for anything **unprofessional, outdated,
+fragile, or sloppy** — deprecated APIs, legacy patterns, swallowed errors, dead
+code, dependency rot, missing tooling, and more — and write an organised,
+evidence-backed issue report to `.edsger/audit/` (`report.md` + `report.json`).
+`edsger review` is an alias.
+
+```bash
+edsger audit                          # audit the current repo
+edsger audit --serve                  # …and open the findings dashboard
+edsger audit --focus "error handling" # concentrate the audit on one concern
+edsger audit --only outdated,dependencies   # restrict to specific dimension ids
+edsger audit --fail-on high           # CI gate: exit 2 on high/critical findings
+edsger audit --json                   # also print JSON to stdout
+edsger audit serve                    # browse existing findings (filter by severity/dimension)
+edsger audit report --html audit.html # export a self-contained shareable viewer
+```
+
+Findings are grouped by dimension (correctness, security, outdated patterns,
+dependency health, error handling, craftsmanship, architecture, testing,
+tooling, docs, performance — plus language-specific dimensions), sorted by
+severity, each with the file/line evidence, why it matters, a concrete fix, and
+an effort estimate. Repeated instances of the same issue are folded into one
+finding listing all locations, and reports are capped at the standard's
+`policy.maxFindings` (default 60, lowest severity dropped first) so they stay
+readable. Low-effort fixes surface in a **Quick wins** section, and runs are
+archived under `.edsger/audit/runs/<timestamp>/` with a `history.jsonl` trend
+index, exactly like `benchmark`.
+
 ### `edsger serve` — dashboard (current, history, trends)
 
 Serve an interactive dashboard for the benchmark results in the current repo —
@@ -99,6 +129,76 @@ The dashboard renders every diagram as Mermaid with per-diagram **zoom**, a
 gets a static Mermaid sanity check whose warnings surface in the CLI, in
 `diagrams.md`, and on the card.
 
+### `edsger mindmap` — implementation mind map of the code
+
+Analyse the repository and build an **implementation mind map**: an outline tree
+whose root is the project and whose branches explain how the code is actually
+implemented — entry points, core flows, module structure, domain model,
+integrations — with every leaf citing the real files it describes. Writes to
+`.edsger/mindmap/` (`mindmap.md` + `mindmap.json`, with each run archived under
+`runs/<timestamp>/`).
+
+```bash
+edsger mindmap                   # mind-map the current repo
+edsger mindmap -C ./service      # …another directory
+edsger mindmap --serve           # generate, then open the interactive viewer
+edsger mindmap --focus "the auth subsystem"   # concentrate the depth somewhere
+edsger mindmap --json            # also print JSON to stdout
+```
+
+The agent detects the project's language(s), loads the matching mind-map
+**standard** (from [edsger-assets](https://github.com/stevenzg/edsger-assets),
+fully overridable), keeps only the branches this project's code supports, and
+grows each into a faithful subtree. `mindmap.md` is a nested outline that reads
+well on GitHub; for the interactive view:
+
+```bash
+edsger mindmap serve             # serve the mind-map viewer
+edsger mindmap report --html mindmap.html   # export a self-contained HTML file
+```
+
+The viewer browses the tree **Workflowy-style**: collapse/expand any node, click
+a bullet to zoom into that subtree (with a breadcrumb back up), navigate with
+the keyboard (↑/↓/←/→, Enter to zoom, Esc to zoom out), and search across
+titles, summaries, and file paths.
+
+### `edsger testcases` — manual test-case plan for the repo
+
+Analyse the repository and derive a **manual test-case plan**: an outline tree
+whose root is the project, whose branches are the areas a human tester should
+exercise — core flows, inputs & edge cases, errors & recovery, data integrity,
+integrations, configuration — and whose leaves are concrete test cases
+(preconditions, exact steps, one expected result, a priority) that a tester who
+has never read the code can execute. These are **not** automated code tests.
+Writes to `.edsger/testcases/` (`testcases.md` + `testcases.json`, with each run
+archived under `runs/<timestamp>/`).
+
+```bash
+edsger testcases                 # derive a test plan for the current repo
+edsger testcases -C ./service    # …another directory
+edsger testcases --serve         # generate, then open the interactive viewer
+edsger testcases --focus "the export feature"   # concentrate the depth somewhere
+edsger testcases --json          # also print JSON to stdout
+```
+
+The agent detects the project's language(s), loads the matching test-case
+**standard** (from [edsger-assets](https://github.com/stevenzg/edsger-assets),
+fully overridable), keeps only the test areas this project's code supports, and
+grounds every case in real behaviour — commands, flags, routes, screens, and
+error branches — citing the files that implement it. `testcases.md` is a nested
+Markdown checklist a tester can tick off; for the interactive view:
+
+```bash
+edsger testcases serve           # serve the test-case viewer
+edsger testcases report --html testcases.html   # export a self-contained HTML file
+```
+
+The viewer browses the plan **Workflowy-style** like the mind map —
+collapse/expand, zoom with breadcrumbs, keyboard navigation, search — plus
+test-case extras: **priority badges** with a filter (critical/high/medium/low),
+per-branch case counts, and expandable case details showing preconditions,
+numbered steps, and the expected result.
+
 ### `edsger pr-review <pr>` (requires `gh`)
 
 Review a pull request against the review standard. Previews by default; pass

package/assets/README.md

@@ -11,6 +11,15 @@ This repository is the canonical source of truth for:
 - **Diagram catalogs** (`diagrams/`) — the professional software diagrams (C4
   architecture, ER, sequence, class, state, data-flow, deployment, and more), when
   each applies to a project, and how to build it as renderable Mermaid.
+- **Mind-map standards** (`mindmap/`) — how to build an implementation mind map
+  of a repository: an outline tree (entry points, core flows, module structure,
+  domain model, integrations) whose leaves cite the real files, browsable
+  Workflowy-style.
+- **Manual test-case standards** (`testcases/`) — how to derive a manual
+  test-case plan from a repository: an outline tree of test areas (core flows,
+  inputs & edge cases, errors & recovery, data integrity, integrations) whose
+  leaves are concrete test cases (preconditions, steps, expected result) a
+  human tester can execute, browsable Workflowy-style.
 
 The content here encodes widely accepted engineering best practices (OWASP, the
 Twelve-Factor App, Google Engineering Practices, SLSA, Keep a Changelog, Semantic
@@ -21,9 +30,10 @@ These standards can be consumed three ways:
 
 1. **The [`edsger`](https://www.npmjs.com/package/edsger) CLI** — bundles these
    assets and runs them with the Claude Agent SDK.
-2. **As a Claude Code plugin** — `/benchmark`, `/pr-review`, `/pr-resolve`, `/diagram`
-   skills that work inside Claude Code with no CLI install (see below).
-3. **Raw YAML** — point any tooling at the files in `benchmark/`, `review/`, and `diagrams/`.
+2. **As a Claude Code plugin** — `/benchmark`, `/pr-review`, `/pr-resolve`, `/diagram`,
+   `/mindmap`, `/testcases` skills that work inside Claude Code with no CLI install (see below).
+3. **Raw YAML** — point any tooling at the files in `benchmark/`, `review/`,
+   `diagrams/`, `mindmap/`, and `testcases/`.
 
 ## Use inside Claude Code (no CLI install)
 
@@ -35,7 +45,7 @@ plugin to get the skills as slash commands:
 /plugin install edsger@edsger-assets
 ```
 
-Then run `/benchmark`, `/pr-review`, `/pr-resolve`, or `/diagram`. The skills read
+Then run `/benchmark`, `/pr-review`, `/pr-resolve`, `/diagram`, `/mindmap`, or `/testcases`. The skills read
 the same YAML from this repo (`${CLAUDE_PLUGIN_ROOT}/benchmark/...`,
 `${CLAUDE_PLUGIN_ROOT}/diagrams/...`) and prefer the `edsger` CLI when it is
 installed, falling back to running natively with Claude Code's own tools.
@@ -47,17 +57,21 @@ edsger-assets/
 ├── .claude-plugin/           # Claude Code plugin + marketplace manifests
 │   ├── plugin.json
 │   └── marketplace.json
-├── skills/                   # Claude Code skills (/benchmark, /pr-review, /pr-resolve, /diagram)
+├── skills/                   # Claude Code skills (/benchmark, /pr-review, /pr-resolve, /diagram, /mindmap, /testcases)
 │   ├── benchmark/SKILL.md
 │   ├── pr-review/SKILL.md
 │   ├── pr-resolve/SKILL.md
-│   └── diagram/SKILL.md
+│   ├── diagram/SKILL.md
+│   ├── mindmap/SKILL.md
+│   └── testcases/SKILL.md
 ├── manifest.yaml              # registry: versions, languages, default chains
 ├── languages.yaml            # language detection heuristics (markers + globs)
 ├── schema/
 │   ├── benchmark.schema.json # JSON Schema for a benchmark rubric
 │   ├── review.schema.json    # JSON Schema for a review standard
-│   └── diagrams.schema.json  # JSON Schema for a diagram catalog
+│   ├── diagrams.schema.json  # JSON Schema for a diagram catalog
+│   ├── mindmap.schema.json   # JSON Schema for a mind-map standard
+│   └── testcases.schema.json # JSON Schema for a manual test-case standard
 ├── benchmark/
 │   ├── base.yaml             # language-agnostic baseline (always applied)
 │   ├── typescript.yaml       # overlays, merged on top of base
@@ -69,9 +83,14 @@ edsger-assets/
 ├── review/
 │   ├── base.yaml
 │   └── …                     # language overlays
-└── diagrams/
-    ├── base.yaml             # universal diagram catalog (C4, ER, sequence, flow, …)
-    └── …                     # language overlays (react tree, JPA model, goroutines, …)
+├── diagrams/
+│   ├── base.yaml             # universal diagram catalog (C4, ER, sequence, flow, …)
+│   └── …                     # language overlays (react tree, JPA model, goroutines, …)
+├── mindmap/
+│   ├── base.yaml             # universal mind-map aspects (entry points, flows, modules, …)
+│   └── …                     # language overlays (package surface, go layout, …)
+└── testcases/
+    └── base.yaml             # universal manual-test areas (core flows, edge cases, errors, …)
 ```
 
 ## How standards are resolved

package/assets/audit/base.yaml

@@ -0,0 +1,187 @@
+id: base
+name: Universal Repository Audit Standard
+version: 0.1.0
+kind: audit
+extends: null
+appliesTo: ["*"]
+
+# Tone for the whole audit: a demanding but fair staff engineer doing a deep
+# professionalism pass over an existing codebase (not a diff).
+guidance: >
+  Hunt for anything that separates this repository from truly professional,
+  industrial-grade work: sloppy or amateurish implementations, outdated or
+  deprecated patterns, hidden fragility, and neglected hygiene. Every finding
+  must cite concrete evidence (file paths, and lines where possible) and come
+  with an actionable fix. Prefer many precise, high-signal findings over vague
+  generalities — but do not invent problems where the code is genuinely fine.
+  When the same issue recurs across many files, consolidate it into ONE finding
+  whose detail lists the affected locations, rather than one finding per file.
+
+policy:
+  # Keep reports readable: findings beyond this cap are dropped lowest-severity
+  # first (the report says how many were omitted).
+  maxFindings: 60
+
+dimensions:
+  - id: correctness
+    title: Correctness & Robustness
+    defaultSeverity: high
+    guidance: >
+      Latent bugs and fragile logic that happen to work today: unhandled edge
+      cases (empty/null, boundaries, unicode, large inputs), off-by-one errors,
+      race conditions, order-dependent behaviour, silent data loss, and
+      incorrect assumptions about the environment (paths, locale, timezone,
+      line endings).
+    checklist:
+      - Edge cases (empty, null, boundary, huge input) are handled
+      - No time-of-check/time-of-use or ordering hazards
+      - Parsing/serialisation round-trips are safe
+      - No reliance on undefined or platform-specific behaviour
+
+  - id: security
+    title: Security & Secrets Hygiene
+    defaultSeverity: critical
+    guidance: >
+      Secrets committed to the repo or baked into defaults, injection risks
+      (command, SQL, path, template), unsafe deserialisation, missing
+      validation of untrusted input, world-readable temp files, disabled TLS
+      verification, and overly broad permissions. Also flag security-relevant
+      hygiene: no dependency audit in CI, no SECURITY.md for public projects.
+    checklist:
+      - No secrets, tokens, or private endpoints in code, config, or history-visible files
+      - Untrusted input is validated; shell/SQL/path construction is safe
+      - Crypto/TLS is not weakened (no verify=false, no home-rolled crypto)
+    references:
+      - "https://owasp.org/www-project-top-ten/"
+
+  - id: outdated
+    title: Outdated & Deprecated Patterns
+    defaultSeverity: medium
+    guidance: >
+      Code written against yesterday's ecosystem: deprecated APIs and language
+      constructs, EOL runtime/toolchain targets, legacy idioms with clearly
+      better modern replacements, polyfills or workarounds for long-fixed
+      issues, and documentation/tooling that references dead services. Modern
+      does not mean fashionable — flag only where the ecosystem has genuinely
+      moved on and the old pattern carries real cost (support, safety, DX).
+    checklist:
+      - No use of APIs the language/framework has deprecated
+      - Runtime/toolchain targets are supported (not end-of-life)
+      - No stale polyfills, shims, or workarounds for long-fixed bugs
+      - Idioms match the current, well-established ecosystem standard
+
+  - id: dependencies
+    title: Dependency Health
+    defaultSeverity: medium
+    guidance: >
+      The dependency tree as a liability: abandoned or unmaintained packages,
+      badly outdated majors, missing or uncommitted lockfiles, duplicated
+      libraries doing the same job, heavyweight dependencies used for one
+      function, and version ranges too loose for reproducible builds.
+    checklist:
+      - Lockfile exists, is committed, and matches the manifest
+      - No abandoned/unmaintained dependencies on critical paths
+      - No duplicate libraries covering the same concern
+      - Dependency count and weight are proportionate to the problem
+
+  - id: error-handling
+    title: Error Handling & Observability
+    defaultSeverity: high
+    guidance: >
+      Swallowed exceptions, catch-all handlers that hide failures, errors
+      logged and then ignored, missing exit codes in CLIs, user-facing messages
+      that leak internals or say nothing, debug prints left in production
+      paths, and absent or unstructured logging where operations would need it.
+    checklist:
+      - No silently swallowed errors or empty catch blocks
+      - Failure paths produce actionable messages and correct exit/status codes
+      - Debug/print statements are not left in production code paths
+      - Logging exists where diagnosing failures would otherwise be impossible
+
+  - id: craftsmanship
+    title: Code Craftsmanship
+    defaultSeverity: medium
+    guidance: >
+      The "unprofessional implementation" catch-all: dead code and commented-out
+      blocks, copy-pasted near-duplicates, magic numbers/strings, misleading or
+      lazy names (data2, temp, doStuff), functions doing five unrelated things,
+      inconsistent style within the repo, typos in identifiers and user-facing
+      text, TODO/FIXME rot with no owner or issue, and clever code where boring
+      code would do.
+    checklist:
+      - No dead code, commented-out blocks, or leftover scaffolding
+      - No copy-paste duplication that should be a shared helper
+      - Names communicate intent; magic values are named constants
+      - TODOs/FIXMEs are either actionable (linked) or removed
+
+  - id: architecture
+    title: Architecture & Structure
+    defaultSeverity: medium
+    guidance: >
+      Structure that will not scale with the project: god files/modules,
+      circular dependencies, business logic welded to I/O or UI, missing
+      layering where it is clearly needed, misplaced responsibilities,
+      configuration scattered across the codebase, and public surface area
+      exposed by accident.
+    checklist:
+      - Responsibilities are separated; no god modules or circular imports
+      - Core logic is separable from I/O, UI, and framework glue
+      - Configuration has a single, discoverable home
+      - Only intentional API surface is exported/public
+
+  - id: testing
+    title: Testing Discipline
+    defaultSeverity: high
+    guidance: >
+      Missing tests for core behaviour, tests that assert nothing meaningful
+      (snapshot dumps, expect(true)), non-deterministic tests (real time,
+      network, ordering), no failure-path coverage, tests not run in CI, and
+      test code held to a visibly lower standard than production code.
+    checklist:
+      - Core behaviour and failure paths are covered by meaningful assertions
+      - Tests are deterministic and independent of network/clock/ordering
+      - Tests run (and gate) in CI
+      - Test code is maintained to production standards
+
+  - id: tooling
+    title: Tooling & Delivery Hygiene
+    defaultSeverity: medium
+    guidance: >
+      The professional baseline around the code: formatter and linter present,
+      configured, and actually enforced; type checking on; CI that builds,
+      lints, and tests every change; sensible .gitignore (no build artifacts or
+      editor droppings committed); reproducible builds; and a release process
+      that is scripted rather than tribal knowledge.
+    checklist:
+      - Formatter + linter configured and enforced (locally and in CI)
+      - CI builds, lints, and tests every push/PR
+      - No build artifacts, caches, or editor files committed
+      - Versioning/release flow is scripted and documented
+
+  - id: docs
+    title: Documentation & Onboarding
+    defaultSeverity: low
+    guidance: >
+      Whether a competent stranger can use and contribute to this repo: README
+      that reflects reality (install, usage, examples that actually run),
+      documented configuration and environment variables, LICENSE present,
+      CHANGELOG maintained, and docs that have not drifted from the code.
+    checklist:
+      - README quick-start actually works as written
+      - Configuration/env vars are documented
+      - LICENSE exists; CHANGELOG (or releases) tracks user-facing change
+      - No documentation that contradicts current behaviour
+
+  - id: performance
+    title: Performance & Resource Waste
+    defaultSeverity: medium
+    guidance: >
+      Obvious waste, not micro-optimisation: accidental O(n^2) on unbounded
+      input, N+1 I/O patterns, whole-file/whole-table loads where streaming is
+      needed, unbounded caches or concurrency, synchronous blocking on hot
+      paths, and resources (handles, connections, watchers) that are never
+      released.
+    checklist:
+      - No accidentally quadratic work or N+1 I/O on unbounded data
+      - Memory and concurrency are bounded
+      - Resources are reliably released on all paths

package/assets/audit/csharp.yaml

@@ -0,0 +1,46 @@
+id: csharp
+name: C# / .NET Audit Overlay
+version: 0.1.0
+kind: audit
+extends: base
+appliesTo: [csharp]
+
+dimensions:
+  - id: cs-legacy
+    title: Legacy .NET Patterns
+    defaultSeverity: medium
+    guidance: >
+      Framework-era habits in a modern .NET codebase: `WebClient` where
+      `HttpClient`/`IHttpClientFactory` is standard, `ArrayList` and other
+      non-generic collections, old-style verbose .csproj, `BinaryFormatter`,
+      and projects targeting out-of-support runtimes.
+    checklist:
+      - HttpClient (properly managed) instead of WebClient
+      - Generic collections; no BinaryFormatter
+      - SDK-style projects targeting supported runtimes
+
+  - id: cs-robustness
+    title: C# Robustness Idioms
+    defaultSeverity: high
+    guidance: >
+      Sync-over-async (`.Result`, `.Wait()`, `GetAwaiter().GetResult()`),
+      `async void` outside event handlers, undisposed `IDisposable`s,
+      exceptions swallowed by empty catches, and nullable reference types
+      disabled or ignored with `!` sprinkled everywhere.
+    checklist:
+      - No sync-over-async or async void on non-event paths
+      - IDisposables are disposed (using/await using)
+      - Nullable reference types enabled and respected
+
+  - id: cs-conventions
+    title: Solution & Style Hygiene
+    defaultSeverity: medium
+    guidance: >
+      The professional baseline: `.editorconfig` with real rules, analyzers
+      (Roslyn/StyleCop) enabled and warnings treated seriously, consistent
+      namespace-to-folder mapping, and central package management where the
+      solution has grown past a couple of projects.
+    checklist:
+      - .editorconfig + analyzers enforced, warnings not suppressed wholesale
+      - Namespaces match folder/project structure
+      - Package versions centrally managed in multi-project solutions

package/assets/audit/dart.yaml

@@ -0,0 +1,46 @@
+id: dart
+name: Dart / Flutter Audit Overlay
+version: 0.1.0
+kind: audit
+extends: base
+appliesTo: [dart]
+
+dimensions:
+  - id: dart-legacy
+    title: Legacy Dart / Flutter Patterns
+    defaultSeverity: medium
+    guidance: >
+      Pre-null-safety code or `// @dart=2.9` opt-outs, deprecated Flutter
+      widgets and theme APIs (e.g. long-removed button classes, textScaleFactor),
+      the retired `pedantic`/`effective_dart` lint packages instead of
+      `flutter_lints`/`lints`, and SDK constraints spanning EOL versions.
+    checklist:
+      - Sound null safety everywhere; no language-version opt-outs
+      - No deprecated widget/theme APIs
+      - Current lints package; supported SDK constraints
+
+  - id: dart-robustness
+    title: Dart Robustness Idioms
+    defaultSeverity: high
+    guidance: >
+      Un-awaited futures without `unawaited()`, `BuildContext` used across
+      async gaps, `setState` after dispose or as a state-management strategy
+      at scale, missing `dispose()` for controllers/streams, and blocking work
+      on the UI isolate.
+    checklist:
+      - Futures awaited or explicitly unawaited; no context-across-async-gap
+      - Controllers/streams/subscriptions are disposed
+      - Heavy work moved off the UI isolate
+
+  - id: dart-conventions
+    title: Project & Pub Hygiene
+    defaultSeverity: medium
+    guidance: >
+      analysis_options.yaml present with meaningful rules, `dart format`
+      enforced, pubspec dependencies tidy (no unused packages, sensible
+      constraints), and generated files (freezed, build_runner output) handled
+      consistently — either committed with a policy or reliably generated.
+    checklist:
+      - analysis_options with enforced lints; formatter clean
+      - pubspec constraints tidy; no unused dependencies
+      - Generated-file policy is consistent

package/assets/audit/go.yaml

@@ -0,0 +1,46 @@
+id: go
+name: Go Audit Overlay
+version: 0.1.0
+kind: audit
+extends: base
+appliesTo: [go]
+
+dimensions:
+  - id: go-legacy
+    title: Legacy Go Patterns
+    defaultSeverity: medium
+    guidance: >
+      Pre-modules and pre-1.x idioms: `io/ioutil` (deprecated since 1.16),
+      `github.com/pkg/errors` where `fmt.Errorf("%w")` and `errors.Is/As` are
+      standard, vendored GOPATH-era layouts, `interface{}` where `any` or
+      generics fit, and toolchain/go directives pinned to unsupported versions.
+    checklist:
+      - No io/ioutil or other deprecated stdlib usage
+      - Error wrapping uses %w / errors.Is / errors.As
+      - go.mod targets a supported Go release
+
+  - id: go-robustness
+    title: Go Robustness Idioms
+    defaultSeverity: high
+    guidance: >
+      Discarded errors (`_ =` or plain ignored returns), `panic` in library
+      code, goroutines launched with no lifecycle or cancellation, missing
+      `context.Context` propagation on blocking/network paths, data races
+      around shared maps/slices, and `defer` misuse in loops.
+    checklist:
+      - Errors are handled or explicitly justified, never silently dropped
+      - No panics in library paths; goroutines have owners and cancellation
+      - context.Context flows through blocking and network calls
+
+  - id: go-idioms
+    title: Go Conventions & Layout
+    defaultSeverity: medium
+    guidance: >
+      Package names that stutter (`user.UserService`), kitchen-sink `util`
+      packages, exported identifiers without doc comments, interfaces declared
+      by the producer instead of the consumer, and repos missing the standard
+      professional baseline (gofmt enforced, go vet / staticcheck in CI).
+    checklist:
+      - Package and identifier naming follows Go conventions (no stutter)
+      - Exported API has doc comments
+      - gofmt + vet/staticcheck are enforced in CI

package/assets/audit/java.yaml

@@ -0,0 +1,46 @@
+id: java
+name: Java Audit Overlay
+version: 0.1.0
+kind: audit
+extends: base
+appliesTo: [java]
+
+dimensions:
+  - id: java-legacy
+    title: Legacy Java Patterns
+    defaultSeverity: medium
+    guidance: >
+      APIs the platform has left behind: `java.util.Date`/`Calendar` where
+      `java.time` is standard, raw generic types, `Vector`/`Hashtable`,
+      hand-rolled resource handling instead of try-with-resources, `javax.*`
+      remnants in a Jakarta world, and builds targeting EOL JDKs.
+    checklist:
+      - java.time used instead of Date/Calendar
+      - No raw types or legacy synchronized collections without cause
+      - Build targets a supported (ideally LTS) JDK
+
+  - id: java-robustness
+    title: Java Robustness Idioms
+    defaultSeverity: high
+    guidance: >
+      Swallowed checked exceptions (catch–printStackTrace–continue),
+      `System.out` logging in production code, null-happy APIs where
+      `Optional` or explicit contracts belong, mutable static state, and
+      equals/hashCode contracts broken or missing on value types.
+    checklist:
+      - No swallowed exceptions or printStackTrace in production paths
+      - A real logging framework is used consistently
+      - Value types honour equals/hashCode; shared state is controlled
+
+  - id: java-build
+    title: Build & Dependency Hygiene
+    defaultSeverity: medium
+    guidance: >
+      Maven/Gradle professionalism: wrapper committed, dependency versions
+      managed centrally (BOM/catalog) rather than sprinkled, no SNAPSHOT
+      dependencies on release paths, and static analysis (ErrorProne,
+      SpotBugs, Checkstyle) wired into the build rather than aspirational.
+    checklist:
+      - Build wrapper is committed and CI uses it
+      - Versions are centrally managed; no stray SNAPSHOTs
+      - Static analysis runs as part of the build

package/assets/audit/python.yaml

@@ -0,0 +1,49 @@
+id: python
+name: Python Audit Overlay
+version: 0.1.0
+kind: audit
+extends: base
+appliesTo: [python]
+
+dimensions:
+  - id: py-legacy
+    title: Legacy Python Patterns
+    defaultSeverity: medium
+    guidance: >
+      Python 2 ghosts and pre-modern idioms: `%` or `.format()` where
+      f-strings are standard, `os.path` gymnastics instead of `pathlib`,
+      `setup.py`/`setup.cfg` where `pyproject.toml` is expected, six/futures
+      compatibility shims, and support claims for EOL interpreter versions.
+    checklist:
+      - No Python 2 compatibility shims or EOL interpreter targets
+      - pyproject.toml is the packaging source of truth
+      - Modern idioms (f-strings, pathlib, dataclasses/enum) where they fit
+
+  - id: py-robustness
+    title: Python Robustness Idioms
+    defaultSeverity: high
+    guidance: >
+      Classic footguns: bare `except:` or `except Exception: pass`, mutable
+      default arguments, shadowing builtins, `assert` for runtime validation,
+      `print` debugging in library code, missing `if __name__ == "__main__"`
+      guards, and un-annotated public functions in a codebase that otherwise
+      uses type hints.
+    checklist:
+      - No bare/blanket excepts that swallow errors
+      - No mutable default arguments
+      - Type hints are present and consistent on public surfaces
+      - No print-debugging or asserts-as-validation in production paths
+
+  - id: py-packaging
+    title: Environment & Packaging Hygiene
+    defaultSeverity: medium
+    guidance: >
+      Reproducibility of the environment: dependencies pinned or locked
+      (uv/poetry/pip-tools), dev vs runtime dependencies separated, a single
+      obvious way to set the project up, and linters/formatters (ruff, black,
+      mypy) configured in pyproject rather than scattered dotfiles — or absent
+      entirely.
+    checklist:
+      - Dependencies are locked/pinned for reproducible installs
+      - Dev and runtime dependencies are separated
+      - Lint/format/type-check tooling is configured and enforced