Metadata-Version: 2.4
Name: lazyuvm
Version: 1.7.9
Summary: Local-first Git-native verification evidence layer for RTL projects, EDA reports, and CI review.
Author: LazyUVM contributors
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/jeonghunx/LazyUVM
Project-URL: Repository, https://github.com/jeonghunx/LazyUVM
Project-URL: Issues, https://github.com/jeonghunx/LazyUVM/issues
Keywords: rtl,systemverilog,uvm,verification,verification-knowledge,eda
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# LazyUVM

[![LazyUVM checked](https://github.com/jeonghunx/LazyUVM/actions/workflows/lazyuvm.yml/badge.svg)](https://github.com/jeonghunx/LazyUVM/actions/workflows/lazyuvm.yml)
[![PyPI release](https://img.shields.io/badge/PyPI-1.7.9-blue)](https://pypi.org/project/lazyuvm/1.7.9/)

Latest release: [v1.7.9](https://github.com/jeonghunx/LazyUVM/releases/tag/v1.7.9) |
PyPI: [lazyuvm 1.7.9](https://pypi.org/project/lazyuvm/1.7.9/)

LazyUVM is a local-first Git-native verification knowledge layer for RTL
projects.

Its job is narrow: keep verification knowledge and simulator output close to
the code, then turn them into evidence a reviewer can inspect in Git and CI.

Spec changed. Did verification follow? LazyUVM keeps the requirement source,
owner, revision, linked coverage/assertion/waiver evidence, and stale-evidence
questions visible before a reviewer has to open the full simulator log.

LazyUVM is not trying to replace VCS, Xcelium, Questa, Verilator, or vManager.
It makes their existing output reviewable, local, Git-tracked, and
CI-friendly.

```text
RTL + lazyuvm.toml + simulator reports
  -> LazyUVM
  -> UVM/cocotb/C-header starters
  -> requirement/spec/register/behavior/coverage/waiver traceability
  -> Markdown/JSON evidence for local review and CI
```

LazyUVM is deliberately local-first: no required cloud service, no required
third-party Python dependencies, and optional local Ollama summaries only when a
user explicitly asks for local AI help.

## See The Output First

If you are evaluating the project from GitHub, start with the generated demo
report:

```text
examples/report_bundle_demo/LazyUVM_Report/index.html
```

![LazyUVM static report bundle overview](docs/assets/lazyuvm-report-bundle-overview.png)

To print the checked-in artifact gallery and verification commands:

```bash
lazyuvm demo gallery
```

To see the v1.4 output-trust close-out checklist:

```bash
lazyuvm demo artifact-stability
```

The screenshot is generated from the checked-in demo bundle, not a mockup.
Long paths, manifest names, and commands wrap inside the cards so the artifact
stays readable in a PR or CI browser view.

That offline static bundle is the product loop in one place:

```text
EDA / coverage / gate / spec / waiver / pack JSON
  -> Verification Evidence Report
  -> HTML pages a reviewer can open from a CI artifact
  -> optional facts-only Reviewer Assistant artifacts in the same bundle
```

No simulator, private PDF, cloud account, or AI setup is needed to inspect the
demo.

## 10-Minute EDA/CI Pilot

If you already have a VCS, Questa, Xcelium, Verilator, LCOV, or generic text
report, do not change your sign-off flow first. Run LazyUVM beside it as a
review artifact:

```bash
lazyuvm demo pilot
lazyuvm demo eda-samples
lazyuvm demo artifact-qa
```

The pilot question is narrow:

```text
Can one existing report become local JSON/Markdown/HTML evidence that a PR
reviewer can understand without opening the full simulator log?
```

If you try it, the most useful feedback is public-safe and specific:

- which EDA report family you tried;
- who owns the requirement or spec change when evidence goes stale;
- whether you can share a tiny anonymized snippet;
- which CI system hosted the artifact;
- where the report bundle made review slower or confusing.

Have private-company feedback but do not want to open a GitHub issue? Use the
question set in [docs/anonymous_feedback_form.md](docs/anonymous_feedback_form.md)
to create or answer a no-login anonymous form. Email should be optional, file
uploads should be disabled, and anonymized workflow shape is enough.

See [docs/pilot_feedback_request.md](docs/pilot_feedback_request.md),
[docs/requirement_ownership.md](docs/requirement_ownership.md), and
[docs/anonymized_requirement_feedback.md](docs/anonymized_requirement_feedback.md)
for safe placeholder examples, start with
[docs/pilot_feedback_summary.md](docs/pilot_feedback_summary.md)
to choose the smallest useful feedback, review
[docs/requirement_map_v1_draft.md](docs/requirement_map_v1_draft.md)
for the proposed v1.8 TOML shape, read
[docs/requirement_stale_scenario_demo.md](docs/requirement_stale_scenario_demo.md)
for the revA-to-revB stale evidence scenario, check
[docs/v1.8_readiness_checklist.md](docs/v1.8_readiness_checklist.md)
for the v1.8 starting scope, then use
[docs/v1.7_eda_ci_pilot_hardening.md](docs/v1.7_eda_ci_pilot_hardening.md)
for the exact feedback shape.

## Try It In 3 Minutes

Install from PyPI:

```bash
pipx install lazyuvm
lazyuvm --version
```

If installation or PATH resolution is the problem, print the platform checklist:

```bash
lazyuvm demo install
```

To audit the full first-use path from install to shareable artifacts:

```bash
lazyuvm demo friction
```

Then print the shortest runnable demo:

```bash
lazyuvm demo quickstart
```

The first-use loop is intentionally small:

```text
install
  -> parse the public demo coverage text
  -> write gate Markdown/JSON
  -> build LazyUVM_Report/index.html
  -> run bundle-doctor before sharing the artifact
```

If you cloned the repository, copy the commands printed by
`lazyuvm demo quickstart`, then open:

```text
LazyUVM_Report/index.html
```

See [docs/first_use_artifact_loop.md](docs/first_use_artifact_loop.md) for the
short checklist of files a first-time reviewer should inspect.

To see the before/after story for a small RTL block:

```bash
lazyuvm demo case-study
```

To attach the same evidence loop to CI, print the copy/paste recipes:

```bash
lazyuvm demo ci
```

To run a one-week pilot on one existing EDA report:

```bash
lazyuvm demo pilot
```

To see the full v1.2 pilot story from fixture to redacted evidence:

```bash
lazyuvm demo pilot-case
```

To try VCS, Questa, Xcelium, Verilator, LCOV, and generic report fixtures:

```bash
lazyuvm demo eda-samples
```

To turn one real company report into a tiny public-safe parser fixture:

```bash
lazyuvm demo fixture-kit
```

To standardize the CI filenames reviewers should look for:

```bash
lazyuvm demo artifact-names
```

To check report links and redaction before CI uploads artifacts:

```bash
lazyuvm demo artifact-qa
```

To keep the first CI screen short during a noisy pilot:

```bash
lazyuvm demo reviewer-noise
```

To create a facts-only reviewer summary without AI:

```bash
lazyuvm review summarize \
  --gate-json LazyUVM_Gate.json \
  --eda-report-json LazyUVM_EDA_Report.json \
  --spec-trace-json LazyUVM_Spec_Trace.json \
  --out LazyUVM_Review_Summary.md \
  --json-out LazyUVM_Review_Summary.json
```

See [docs/review_summary.md](docs/review_summary.md) for the command boundary
and output contract.

To create the deterministic reviewer checklist for the same evidence:

```bash
lazyuvm review checklist \
  --gate-json LazyUVM_Gate.json \
  --eda-report-json LazyUVM_EDA_Report.json \
  --spec-trace-json LazyUVM_Spec_Trace.json \
  --redaction-json LazyUVM_Redaction_Check.json \
  --out LazyUVM_Review_Checklist.md \
  --json-out LazyUVM_Review_Checklist.json
```

See [docs/review_checklist.md](docs/review_checklist.md) for the checklist
items and output contract.

To turn the checklist into the first ordered repair queue:

```bash
lazyuvm review next-actions \
  --checklist-json LazyUVM_Review_Checklist.json \
  --out LazyUVM_Review_Next_Actions.md \
  --json-out LazyUVM_Review_Next_Actions.json
```

See [docs/review_next_actions.md](docs/review_next_actions.md) for the queue
ordering and output contract.

To create review-only TOML draft snippets without editing project files:

```bash
lazyuvm review toml-draft \
  --next-actions-json LazyUVM_Review_Next_Actions.json \
  --out LazyUVM_Review_TOML_Draft.md \
  --json-out LazyUVM_Review_TOML_Draft.json
```

See [docs/review_toml_draft.md](docs/review_toml_draft.md) for the draft
boundary and output contract.

To state a low-risk pilot posture before changing merge policy:

```bash
lazyuvm review pilot-safe \
  --next-actions-json LazyUVM_Review_Next_Actions.json \
  --out LazyUVM_Review_Pilot_Safe.md \
  --json-out LazyUVM_Review_Pilot_Safe.json
```

See [docs/review_pilot_safe.md](docs/review_pilot_safe.md) for the
artifact-only, warning-first pilot boundary.

To create an optional local-AI explanation artifact, keep AI off first:

```bash
lazyuvm review explain \
  --next-actions-json LazyUVM_Review_Next_Actions.json \
  --facts-out LazyUVM_Review_AI_Facts.json \
  --prompt-out LazyUVM_Review_AI_Prompt.txt \
  --out LazyUVM_Review_AI_Explanation.md \
  --json-out LazyUVM_Review_AI_Explanation.json
```

Add `--ai --model <ollama-model>` only after your team approves local AI use.
See [docs/review_ai_explain.md](docs/review_ai_explain.md).

To include those facts-only reviewer artifacts in the static HTML bundle:

```bash
lazyuvm report bundle \
  --gate-json LazyUVM_Gate.json \
  --review-summary-json LazyUVM_Review_Summary.json \
  --review-checklist-json LazyUVM_Review_Checklist.json \
  --review-next-actions-json LazyUVM_Review_Next_Actions.json \
  --review-toml-draft-json LazyUVM_Review_TOML_Draft.json \
  --review-pilot-safe-json LazyUVM_Review_Pilot_Safe.json \
  --review-ai-explain-json LazyUVM_Review_AI_Explanation.json \
  --review-ai-facts-json LazyUVM_Review_AI_Facts.json \
  --out LazyUVM_Report
```

The generated `review.html` page keeps the boundary explicit:
generated from local LazyUVM facts, not sign-off, human review required.

To check shareable evidence for local path-like strings:

```bash
lazyuvm report redact-check LazyUVM_CI_Summary.md LazyUVM_Report
```

To lock a fixture into regression evidence:

```bash
lazyuvm coverage fixture-check examples/coverage_reports/vcs_urg.txt \
  --expected examples/coverage_reports/expected/vcs_urg.expected.json
```

The checked-in fixture matrix covers VCS, Questa, Xcelium, Verilator/LCOV,
generic text, and a custom-hints example. See
[docs/eda_fixture_matrix.md](docs/eda_fixture_matrix.md).

If your local report uses custom wording, add TOML hints before changing
Python:

```bash
lazyuvm coverage parse examples/coverage_reports/custom_hint_text.txt \
  --hints examples/coverage_reports/hints/custom_report_hints.toml \
  --json-out LazyUVM_EDA_Report.json
```

Or run the same first evidence loop directly:

```bash
lazyuvm coverage doctor examples/coverage_report.txt

lazyuvm coverage parse examples/coverage_report.txt \
  --json-out LazyUVM_EDA_Report.json \
  --out LazyUVM_EDA_Report.md

lazyuvm gate \
  --config examples/governance_demo.toml \
  --eda-report-json LazyUVM_EDA_Report.json \
  --report LazyUVM_Gate.md \
  --json-out LazyUVM_Gate.json

lazyuvm report bundle \
  --gate-json LazyUVM_Gate.json \
  --eda-report-json LazyUVM_EDA_Report.json \
  --redact-local-paths \
  --out LazyUVM_Report
```

Open `LazyUVM_Report/index.html`. The sample intentionally contains reviewable
coverage holes, so a `FAIL` gate is still a successful first run: the useful
output is the evidence that explains why review is needed.

This path does not require a simulator, private spec PDF, cloud service, or
local AI.

For GitHub Actions, GitLab CI, and Jenkins sketches, see
[docs/eda_ci_recipes.md](docs/eda_ci_recipes.md). For a GitLab/Jenkins-first
pilot checklist, see [docs/gitlab_jenkins_pilot.md](docs/gitlab_jenkins_pilot.md).
For stable artifact names across those systems, see
[docs/ci_artifact_naming_policy.md](docs/ci_artifact_naming_policy.md).
For CI-side artifact QA checks, see
[docs/ci_artifact_qa_recipe.md](docs/ci_artifact_qa_recipe.md).
For shorter first-screen summaries, see
[docs/reviewer_noise_reduction.md](docs/reviewer_noise_reduction.md).
For path-leak checks before sharing evidence, see
[docs/redaction_doctor.md](docs/redaction_doctor.md).

For a small team pilot kit, see
[docs/pilot_adoption_kit.md](docs/pilot_adoption_kit.md). For the shorter
workflow note, see [docs/eda_ci_pilot_workflow.md](docs/eda_ci_pilot_workflow.md).
For the v1.2 fixture-to-redacted-evidence story, see
[docs/eda_ci_pilot_case_study.md](docs/eda_ci_pilot_case_study.md).
For a public-safe feedback template after a pilot review, see
[docs/pilot_feedback_request.md](docs/pilot_feedback_request.md) and
[examples/pilot_feedback/pilot_feedback.md](examples/pilot_feedback/pilot_feedback.md).
For the v1.2 stabilization summary, see
[docs/v1.2_pilot_friction_stabilization.md](docs/v1.2_pilot_friction_stabilization.md).
To see what the v1.1 pilot line considers stable, read
[docs/v1.1_eda_ci_stabilization.md](docs/v1.1_eda_ci_stabilization.md).
For the v1.7 EDA/CI pilot-hardening target, read
[docs/v1.7_eda_ci_pilot_hardening.md](docs/v1.7_eda_ci_pilot_hardening.md).

## Try A Trusted Starter Pack

This is not a public package registry. It is a local catalog of curated starter
packs that can be inspected before a project imports anything:

```bash
lazyuvm pack catalog
lazyuvm pack catalog --json --out examples/apb_timer_cocotb/evidence/pack_catalog.json
lazyuvm pack inspect community/apb
lazyuvm pack inspect community/apb --json --out examples/apb_timer_cocotb/evidence/apb_pack_inspect.json
```

The catalog currently lists the shipped `community/apb`, `community/axi_lite`,
and `community/spi` starters with version, supported export targets, smoke
evidence, known limits, and review policy.

`pack inspect` is the pre-import review packet for one pack. It prints the
pack evidence, bundle summary, known limits, dependency snippet, and adoption
commands before any TOML is imported into a project.

Safe adoption sequence:

```text
catalog -> inspect -> import reviewable TOML -> lock -> overlay diff -> gate/report bundle
```

That sequence is the durable reuse loop: reviewed pack knowledge becomes local
Git evidence rather than a hidden registry install.

To print the full copy/paste adoption recipe:

```bash
lazyuvm demo pack-adoption
```

The checked-in APB adoption example keeps reviewable evidence under
`examples/apb_timer_cocotb/evidence/`.

## Product Boundary

LazyUVM is not a simulator.

LazyUVM is not a vManager replacement.

LazyUVM is not sign-off verification.

It sits next to those tools as a Git-native evidence layer:

```text
VCS / Xcelium / Questa / Verilator / existing reports
  -> LazyUVM normalized evidence
  -> Git review, CI summaries, manifests, and local knowledge reuse
```

The best first use case is not "replace the enterprise flow." It is:

```text
existing EDA output
  -> reviewable LazyUVM evidence
  -> easier PR review, onboarding, and local audit trails
```

## Why Use It

Most verification projects lose knowledge across specs, spreadsheets, old
emails, waiver notes, coverage reports, and personal debug history. LazyUVM is
worth trying when that loss costs review time:

| Need | LazyUVM gives you |
| --- | --- |
| Start a project quickly | RTL scan, project config, starter UVM/SVA/coverage/cocotb output |
| Keep intent reviewable | `lazyuvm.toml` protocol maps, register maps, behavior specs, spec references |
| Reuse knowledge | curated pack catalog, reviewed pattern packs, local pack dependencies, lockfiles, overlay diffs |
| Review simulator output | normalized `lazyuvm.eda_report.v1` JSON from VCS/Questa/Xcelium/Verilator-style reports |
| Keep CI honest | `lazyuvm gate` Markdown/JSON evidence, waiver checks, manifest verification |
| Use AI safely | facts-only context for optional local Ollama explanations; humans still approve |

The useful stickiness is not hidden telemetry. It is the team's reviewed
verification knowledge living in Git.

## Pick Your Path

LazyUVM has a lot of commands, but most users should start with only one path:

| User | Start with | Add later | Avoid at first |
| --- | --- | --- | --- |
| Student / open-source RTL | `demo quickstart`, `check`, `uvm`, `cocotb`, `coverage parse` | `regs --c-header`, `spec --coverage-plan` | strict gates, waivers, pack policy |
| Solo developer / small team | `init`, `check`, `gate`, `know trace`, `know manifest` | reviewed waivers, pack reuse, `init-ci` | enterprise-style process too early |
| Startup / design house | CI gate, EDA report JSON, C headers, cocotb/UVM starters | pack lockfiles, overlay diff, waiver governance | public packs without review |
| Enterprise / existing EDA flow | `coverage parse`, `gate --eda-report-json`, offline/security docs | strict waiver policy, manifests, local AI review bundle | claims of sign-off replacement |

The adoption rule is simple: begin with local evidence, then add governance only
when the team is ready to review it.

For team-level defaults, start with
[docs/team_policy_profiles.md](docs/team_policy_profiles.md). The v1.5 line
closed around a starter file, drift checks, gate/report QA posture,
waiver/security/spec-reference defaults, profile-aware CI snippets, and
commit-vs-artifact ownership:

```bash
lazyuvm policy init --profile startup
lazyuvm policy doctor --file lazyuvm_policy.toml
lazyuvm policy gate-preset --file lazyuvm_policy.toml
lazyuvm policy defaults --file lazyuvm_policy.toml
lazyuvm policy ci-snippet --file lazyuvm_policy.toml --system github --coverage-report reports/vcs_urg.txt
lazyuvm policy adoption-checklist --file lazyuvm_policy.toml
```

To inspect a tiny public-safe policy CI fixture before touching your own flow,
open [examples/policy_ci_demo/README.md](examples/policy_ci_demo/README.md).
For the v1.5 close-out and v1.6 handoff, see
[docs/v1.5_team_policy_stabilization.md](docs/v1.5_team_policy_stabilization.md).

The `education`, `open-source`, `startup`, and `enterprise` profiles make team
risk defaults visible before stricter gates are enabled.

## Install

From a checkout:

```bash
python3 -m pip install -e .
lazyuvm --version
```

For command discovery:

```bash
lazyuvm --help
lazyuvm demo --help
```

For Windows, WSL, Linux, macOS, pipx, and local-checkout troubleshooting, see
[docs/install.md](docs/install.md).

Older one-off flags still exist behind `lazyuvm legacy --help`, but new project
work should use `lazyuvm.toml` and the project commands below.

## Five-Minute Path

Create a project config:

```bash
lazyuvm init --filelist path/to/files.f --top your_top_module
```

Run local checks and starter exports:

```bash
lazyuvm check
lazyuvm uvm --dry-run --diff
lazyuvm uvm
lazyuvm cocotb --out-dir generated_cocotb --dry-run --diff
lazyuvm cocotb --out-dir generated_cocotb
lazyuvm regs --c-header --out regs.h
```

Generated starters use no-overwrite defaults. If a generated file already
exists with different contents, LazyUVM stops and asks for `--force`; use
`--dry-run --diff` first to review the change.

Validate reviewed knowledge:

```bash
lazyuvm regs
lazyuvm spec
lazyuvm know trace --out LazyUVM_Traceability.md
lazyuvm know manifest --out LazyUVM_Knowledge_Manifest.json
```

Turn the current state into CI evidence:

```bash
lazyuvm gate --update-manifest --json-out LazyUVM_Gate.json --report LazyUVM_Gate.md
```

Add GitHub Actions when the local flow is stable:

```bash
lazyuvm init-ci --filelist path/to/files.f --top your_top_module --repo OWNER/REPO --cocotb
```

The generated workflow uploads `lazyuvm-report-bundle`; open
`LazyUVM_Report/index.html` from the artifact for the static HTML dashboard.

## EDA Report Flow

LazyUVM v0.7 adds a small adapter contract for simulator and coverage reports.
The goal is to absorb report output into the same Git-reviewed evidence loop,
not to replace the simulator.

```bash
lazyuvm coverage doctor reports/vcs_urg.txt \
  --tool auto \
  --json-out LazyUVM_EDA_Doctor.json \
  --out LazyUVM_EDA_Doctor.md

lazyuvm coverage parse reports/vcs_urg.txt \
  --tool vcs \
  --json-out LazyUVM_EDA_Report.json \
  --out LazyUVM_EDA_Report.md

lazyuvm gate \
  --eda-report-json LazyUVM_EDA_Report.json \
  --json-out LazyUVM_Gate.json \
  --report LazyUVM_Gate.md

lazyuvm spec trace --json --out LazyUVM_Spec_Trace.json
```

Bundle the local JSON evidence into a static CI artifact:

```bash
lazyuvm report bundle \
  --gate-json LazyUVM_Gate.json \
  --eda-report-json LazyUVM_EDA_Report.json \
  --spec-trace-json LazyUVM_Spec_Trace.json \
  --pack-deps-json pack_dependencies.json \
  --pack-lock-json LazyUVM_Pack_Lock.json \
  --pack-overlay-json pack_overlay_diff.json \
  --pack-catalog-json pack_catalog.json \
  --redact-local-paths \
  --out LazyUVM_Report
```

Create a short CI/PR first-screen summary:

```bash
lazyuvm report ci-summary \
  --gate-json LazyUVM_Gate.json \
  --eda-report-json LazyUVM_EDA_Report.json \
  --eda-doctor-json LazyUVM_EDA_Doctor.json \
  --artifact-name lazyuvm-eda-evidence \
  --out LazyUVM_CI_Summary.md
```

The summary starts with a `Reviewer Focus` table: gate blockers, critical
holes, waiver blockers, spec warnings, pack issues, and EDA parse warnings.
It is meant to tell a reviewer where to look first, not to replace the attached
JSON/Markdown/HTML evidence.

Open `LazyUVM_Report/index.html` for the overview,
`LazyUVM_Report/coverage.html` for coverage-hole review,
`LazyUVM_Report/waivers.html` for waiver health, or
`LazyUVM_Report/spec_trace.html` for source-coordinate traceability, or
`LazyUVM_Report/packs.html` for local pack reuse evidence.
The coverage page includes no-JS reviewer controls for jumping directly to
critical holes, warning holes, other real holes, and sample guidance rows.
Suggested next commands and waiver TOML section paths are rendered as
copy-friendly static blocks for CI environments where JavaScript is disabled.

To preview the result without running a simulator or CI, open the public-safe
demo bundle at
`examples/report_bundle_demo/LazyUVM_Report/index.html`.

The bundle is offline by construction: no CDN, no external JavaScript, no
tracking, no network calls, copied JSON evidence under `data/`, a
`data/manifest.json` inventory, and a `data/manifest.sha256` sidecar. Pack
metadata and smoke-evidence links are copied into `data/pack_evidence/` so the
HTML artifact remains browsable after CI upload. Use `--redact-local-paths`
before sharing a report outside your machine or CI boundary.

Report bundles use quiet artifact branding by default. The page title is
`Verification Evidence Report`; LazyUVM remains as generator provenance with
the tool version, schema, and no-network boundary. Use `--title` for a
project-specific title or `--brand product` for product-branded public demos.
Run `lazyuvm report bundle-doctor LazyUVM_Report` to check local report links,
pack evidence copies, bundled input files, and the manifest digest before
sharing or archiving the artifact.
For a short reviewer reading path, use
[docs/report_bundle_reviewer_guide.md](docs/report_bundle_reviewer_guide.md).
The static HTML policy is documented in
[docs/report_bundle_interactivity_policy.md](docs/report_bundle_interactivity_policy.md).

Supported starter profiles:

| Profile | Typical source |
| --- | --- |
| `vcs` | Synopsys VCS URG-style summaries |
| `questa` | Siemens Questa vcover-style summaries |
| `xcelium` | Cadence Xcelium IMC-style summaries |
| `verilator` / `lcov` | Verilator and LCOV-style text reports |
| `generic` | simple line-oriented coverage notes |

See [docs/v0.7_stabilization.md](docs/v0.7_stabilization.md) for the stable
`lazyuvm.eda_report.v1` fields and the `coverage parse -> gate` handoff.
See [docs/report_bundle.md](docs/report_bundle.md) for the v0.8 static report
bundle contract.

## Typical Team Workflow

1. Commit `lazyuvm.toml`.
2. Add reviewed protocol/register/behavior/spec references as the project
   becomes understood.
3. Parse coverage or simulator reports into LazyUVM JSON.
4. Run `lazyuvm gate` locally and in CI.
5. Review Markdown/JSON evidence in pull requests.
6. Use packs, waivers, and manifests only when the team actually needs them.

That progression matters. Teams should not start by enabling every feature.
Start with a small reviewed config, then add governance as it pays for itself.

## Documentation Map

Do not read every document first. Pick one path:

| If you want to... | Start here |
| --- | --- |
| Find a runnable sample | [examples/README.md](examples/README.md) |
| See a small RTL before/after adoption story | [docs/case_study_small_rtl.md](docs/case_study_small_rtl.md) |
| Run a 10-minute or one-week EDA/CI pilot | [docs/pilot_feedback_request.md](docs/pilot_feedback_request.md), [docs/v1.7_eda_ci_pilot_hardening.md](docs/v1.7_eda_ci_pilot_hardening.md), [docs/pilot_adoption_kit.md](docs/pilot_adoption_kit.md), [docs/eda_ci_pilot_workflow.md](docs/eda_ci_pilot_workflow.md), [docs/eda_ci_pilot_case_study.md](docs/eda_ci_pilot_case_study.md), [docs/v1.2_pilot_friction_stabilization.md](docs/v1.2_pilot_friction_stabilization.md), [docs/v1.1_eda_ci_stabilization.md](docs/v1.1_eda_ci_stabilization.md) |
| Prepare a custom EDA parser fixture | [docs/eda_fixture_adoption_kit.md](docs/eda_fixture_adoption_kit.md) |
| Check fixture parser regressions | [docs/eda_fixture_harness.md](docs/eda_fixture_harness.md) |
| Review the anonymized fixture matrix | [docs/eda_fixture_matrix.md](docs/eda_fixture_matrix.md) |
| Add custom parser hints | [docs/eda_custom_parser_hints.md](docs/eda_custom_parser_hints.md) |
| Standardize CI artifact names | [docs/ci_artifact_naming_policy.md](docs/ci_artifact_naming_policy.md) |
| Add CI artifact QA checks | [docs/ci_artifact_qa_recipe.md](docs/ci_artifact_qa_recipe.md) |
| Pilot with GitLab or Jenkins | [docs/gitlab_jenkins_pilot.md](docs/gitlab_jenkins_pilot.md) |
| Reduce reviewer noise | [docs/reviewer_noise_reduction.md](docs/reviewer_noise_reduction.md) |
| Check evidence redaction | [docs/redaction_doctor.md](docs/redaction_doctor.md) |
| Review a static report bundle | [docs/report_bundle_reviewer_guide.md](docs/report_bundle_reviewer_guide.md) |
| Understand the v1.3 UX line | [docs/v1.3_report_bundle_ux_stabilization.md](docs/v1.3_report_bundle_ux_stabilization.md) |
| Run the first-use artifact loop | [docs/first_use_artifact_loop.md](docs/first_use_artifact_loop.md), [docs/new_user_friction_audit.md](docs/new_user_friction_audit.md) |
| Preview the public demo gallery | [docs/public_demo_gallery.md](docs/public_demo_gallery.md), [examples/report_bundle_demo/README.md](examples/report_bundle_demo/README.md) |
| Check artifact QA before sharing | [docs/v1.4_artifact_qa_baseline.md](docs/v1.4_artifact_qa_baseline.md) |
| Understand the v1.4 output-trust close-out | [docs/v1.4_artifact_trust_stabilization.md](docs/v1.4_artifact_trust_stabilization.md) |
| Choose a team policy profile | [docs/team_policy_profiles.md](docs/team_policy_profiles.md) |
| Guard public demo artifacts | [docs/golden_artifact_snapshots.md](docs/golden_artifact_snapshots.md) |
| Try the product flow | [docs/team_governance_demo.md](docs/team_governance_demo.md) |
| Understand PR repair commands | [docs/pr_workflow_cookbook.md](docs/pr_workflow_cookbook.md) |
| Export UVM, cocotb, C headers, and CI evidence | [docs/export_targets.md](docs/export_targets.md) |
| Reuse local knowledge packs | [docs/pack_reuse_workflow.md](docs/pack_reuse_workflow.md) |
| Adopt a curated starter pack safely | [docs/pack_adoption_recipe.md](docs/pack_adoption_recipe.md) |
| Author a third-party pack | [docs/pack_author_guide.md](docs/pack_author_guide.md) |
| Propose a pack contribution | [docs/pack_contribution_template.md](docs/pack_contribution_template.md) |
| Understand the registry experiment | [docs/registry_experiment.md](docs/registry_experiment.md) |
| Review v1.0 format readiness | [docs/v1_readiness_audit.md](docs/v1_readiness_audit.md) |
| Parse EDA reports in CI | [docs/eda_ci_recipes.md](docs/eda_ci_recipes.md) |
| Review offline/security boundaries | [docs/security_adoption_kit.md](docs/security_adoption_kit.md), [docs/eda_offline_adoption.md](docs/eda_offline_adoption.md) |
| Use local AI safely | [docs/facts_only_ai.md](docs/facts_only_ai.md), [docs/reviewer_artifacts_in_report_bundle.md](docs/reviewer_artifacts_in_report_bundle.md), [docs/v1.6_reviewer_assistant_stabilization.md](docs/v1.6_reviewer_assistant_stabilization.md), [docs/ai_review_workflow.md](docs/ai_review_workflow.md) |

The full documentation index is [docs/README.md](docs/README.md).

## Local AI Boundary

LazyUVM does not ask AI to sign off RTL.

Start with [docs/facts_only_ai.md](docs/facts_only_ai.md) before enabling any
local model in a team flow.

```text
LazyUVM = extract facts, link evidence, write stable JSON/Markdown
AI      = optionally explain those facts in local prose
Human   = review, approve, sign off
```

Useful commands:

```bash
lazyuvm review summarize --gate-json LazyUVM_Gate.json --out LazyUVM_Review_Summary.md
lazyuvm review checklist --gate-json LazyUVM_Gate.json --out LazyUVM_Review_Checklist.md
lazyuvm review next-actions --checklist-json LazyUVM_Review_Checklist.json --out LazyUVM_Review_Next_Actions.md
lazyuvm review toml-draft --next-actions-json LazyUVM_Review_Next_Actions.json --out LazyUVM_Review_TOML_Draft.md
lazyuvm review pilot-safe --next-actions-json LazyUVM_Review_Next_Actions.json --out LazyUVM_Review_Pilot_Safe.md
lazyuvm review explain --next-actions-json LazyUVM_Review_Next_Actions.json --facts-out LazyUVM_Review_AI_Facts.json --prompt-out LazyUVM_Review_AI_Prompt.txt --out LazyUVM_Review_AI_Explanation.md
lazyuvm know context "coverage closure" --gate-json LazyUVM_Gate.json --out LazyUVM_AI_Context.json
lazyuvm know context-verify LazyUVM_AI_Context.json
lazyuvm know prompt --context-json LazyUVM_AI_Context.json --out LazyUVM_AI_Prompt.txt
lazyuvm know explain "coverage closure" --context-json LazyUVM_AI_Context.json --ai --out LazyUVM_Knowledge_Explain.md
lazyuvm know guard --context-json LazyUVM_AI_Context.json --ai-output LazyUVM_Knowledge_Explain.md
```

Start with `lazyuvm review summarize`, `lazyuvm review checklist`, and
`lazyuvm review next-actions` before enabling optional local AI. They are
deterministic, use attached LazyUVM JSON facts only, and do not approve
waivers, close coverage, infer PDF contents, or mutate project files.

`lazyuvm review toml-draft` emits copyable placeholder TOML snippets for human
review. It never edits `lazyuvm.toml` or waiver files.

`lazyuvm review pilot-safe` emits an artifact-only, warning-first pilot posture.
It is the command to show a team that LazyUVM can sit beside the existing flow
before anyone changes merge gates or policy settings.

`lazyuvm review explain` is the first optional local-AI bridge. It still keeps
AI off unless `--ai` is passed. Use `--facts-out` and `--prompt-out` when a
reviewer needs to inspect the exact facts and prompt used for the optional
local explanation.

AI output is a reading aid, not a reviewed fact or root-cause decision.
For the v1.6 close-out and v1.7 handoff, see
[docs/v1.6_reviewer_assistant_stabilization.md](docs/v1.6_reviewer_assistant_stabilization.md).

## Who It Is For

LazyUVM is a practical fit for:

- students and open-source RTL projects that need repeatable verification
  structure without enterprise tooling;
- small teams that want Git-reviewed protocol/register/spec knowledge;
- teams already using commercial simulators but wanting lightweight PR evidence;
- engineers who want local-first AI summaries without uploading design data.

It is not a substitute for a mature enterprise sign-off flow. If your company
already has vManager, Verdi, VCS, Xcelium, Questa, Jasper, or internal dashboards,
LazyUVM should complement that flow by making local evidence easier to review.

For enterprise conversations, the safest framing is:

```text
LazyUVM does not replace the enterprise flow.
LazyUVM turns local RTL knowledge and EDA output into reviewable Git/CI evidence.
```

## Release Status

Current repository version: `1.7.9`

Latest tagged release: `1.7.9`

Latest release note: [docs/releases/v1.7.9.md](docs/releases/v1.7.9.md)

v1.0 means format stability for local verification knowledge and CI evidence,
not simulator replacement or sign-off replacement.

See [CHANGELOG.md](CHANGELOG.md) for release history and
[RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md) before cutting a tag.

For small public-safe contributions, see [CONTRIBUTING.md](CONTRIBUTING.md).
For sensitive reports and private design-data boundaries, see
[SECURITY.md](SECURITY.md).

## Project Philosophy

The project is intentionally boring where it matters:

- local files over hidden services;
- reviewable TOML/JSON/Markdown over opaque databases;
- explicit spec/register/behavior links over magic inference;
- deterministic CI evidence over unverifiable AI claims;
- human approval over automated sign-off.

That is the adoption path: make the first local workflow useful, then let teams
keep more of their verification memory in a format they can review, diff, and
carry between projects.
