Metadata-Version: 2.4
Name: lazyuvm
Version: 0.5.2
Summary: Local-first RTL verification knowledge platform for UVM scaffolds, reviewed maps, pattern packs, and CI gates.
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 :: 3 - Alpha
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)

LazyUVM is a local-first RTL verification knowledge platform. Bootstrap UVM
environments, capture reviewed verification knowledge, and generate CI-readable
evidence from local RTL projects.

The same reviewed `lazyuvm.toml` knowledge can feed UVM starters, cocotb
starters, firmware-facing C headers, source traceability, pack compatibility
checks, and CI evidence. UVM is one export target, not the whole product.

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

The `LazyUVM checked` badge means the repository's smoke checks pass on GitHub Actions. It is a quick project-health signal, not silicon sign-off.

## Product Boundary

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

```text
LazyUVM is not a simulator.
LazyUVM is not a vManager replacement.
LazyUVM is not sign-off verification.
```

It is the local layer for project bring-up, reviewed protocol/register/behavior
knowledge, accepted waivers, pattern reuse, manifests, and CI-readable evidence.

## Product Shape

LazyUVM has four connected workflows:

| Layer | What it does | Main commands |
| --- | --- | --- |
| Bootstrap | Scan RTL, resolve filelists, infer obvious protocols, generate starter UVM/SVA/coverage/cocotb artifacts, emit tool commands, list export targets, and run smoke checks. | `check`, `uvm`, `cocotb`, `tools emit`, `tools targets`, `quality`, `report`, `regress` |
| Knowledge | Commit reviewable protocol maps, register maps, behavior specs, reviewed patterns, and portable bundles. | `regs`, `spec`, `pack`, `suggest-protocol-map`, `suggest-register-map` |
| Workflow | Search, explain, recommend, trace, and snapshot the local verification knowledge that a team has reviewed. | `know query`, `know explain`, `know recommend`, `know trace`, `know manifest` |
| CI Gate | Turn the reviewed knowledge state into repeatable Markdown/JSON evidence for pull requests and releases. | `gate`, `init-ci`, `baseline diff`, `pack manifest-verify` |

The useful moat is the Git-friendly knowledge format, not hidden telemetry:

```text
RTL + protocol maps + register maps + behavior specs + reviewed pattern packs
  -> LazyUVM
  -> UVM/cocotb starters + C headers + traceability + manifests + CI gate reports
```

## Local AI Over Facts

LazyUVM does not ask AI to sign off RTL. It first turns local project state into
reviewable facts, then optionally asks local Ollama to explain those facts:

```bash
lazyuvm gate --update-manifest --json-out LazyUVM_Gate.json
lazyuvm know explain "coverage closure" --gate-json LazyUVM_Gate.json --json --out LazyUVM_Knowledge_Explain.json
lazyuvm know explain "coverage closure" --gate-json LazyUVM_Gate.json --ai --out LazyUVM_Knowledge_Explain.md
```

The report starts with a reviewer summary, then includes the underlying
`fact_context`: gate status, spec trace, coverage trace, waiver doctor state,
and behavior plan cards. AI output is a local reading aid, not a reviewed fact
or root-cause decision.

## Typical Team Workflow

Most teams should start with the short project commands, then drop into the
older direct flags only for one-off scans.

1. Initialize the project once:

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

2. Commit the reviewed project knowledge:

   ```bash
   lazyuvm suggest-protocol-map --module your_top_module --out suggested_protocol.toml
   lazyuvm suggest-register-map --module your_top_module --out suggested_registers.toml
   lazyuvm regs
   lazyuvm regs --c-header --out regs.h
   lazyuvm cocotb --out-dir generated_cocotb
   lazyuvm spec --cocotb-plan --out LazyUVM_cocotb_plan.md
   lazyuvm spec --cocotb-plan --json --out LazyUVM_cocotb_plan.json
   lazyuvm spec
   ```

3. Run the daily local gate:

   ```bash
   lazyuvm check
   lazyuvm quality --strict
   lazyuvm gate --update-manifest --json-out LazyUVM_Gate.json
   ```

4. Wire the same flow into GitHub Actions:

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

5. During review, inspect the evidence instead of rereading every config file:

   ```bash
   lazyuvm know query "apb timeout"
   lazyuvm know trace --out LazyUVM_Traceability.md
   lazyuvm know manifest-verify LazyUVM_Knowledge_Manifest.json
   lazyuvm gate --strict --manifest LazyUVM_Knowledge_Manifest.json
   ```

   Traceability links behavior specs to register maps, reviewed debug patterns,
   and configured coverage holes from `reports.coverage_report`.

For the shortest coverage-governance walkthrough, start with
[docs/team_governance_demo.md](docs/team_governance_demo.md) and the curated
sample artifacts in [examples/governance_demo/](examples/governance_demo/).
For the v0.4 HW/SW/cocotb export loop, use
[docs/export_governance_demo.md](docs/export_governance_demo.md) and
[examples/apb_timer_cocotb/](examples/apb_timer_cocotb/), or run
`lazyuvm demo export-governance`.
When CI warns or fails, use
[docs/pr_workflow_cookbook.md](docs/pr_workflow_cookbook.md) for copy/paste
repair loops covering unlinked holes, accepted waivers, stale manifests, and
baseline deltas. For a short terminal reminder, run `lazyuvm demo next-steps`;
the UX rule set lives in [docs/governance_ux_polish.md](docs/governance_ux_polish.md).
For team adoption and security review, see
[docs/security_offline.md](docs/security_offline.md),
[docs/not_a_vmanager_replacement.md](docs/not_a_vmanager_replacement.md),
[docs/adoption_for_small_teams.md](docs/adoption_for_small_teams.md), and
[docs/enterprise_positioning.md](docs/enterprise_positioning.md). Public-facing
wording is pinned in [docs/public_positioning.md](docs/public_positioning.md).
The first curated starter pack skeleton is
[packs/community/apb/](packs/community/apb/); validate it with
`lazyuvm pack metadata-validate packs/community/apb/pack.toml` and
`lazyuvm pack bundle-validate packs/community/apb/bundle.json`. Projects can
then declare reviewed local reuse intent with `[pack_dependencies.*]` and check
it with `lazyuvm pack dependencies`:

```toml
[pack_dependencies.apb]
name = "community/apb"
path = "packs/community/apb"
version = "0.4.8"
min_lazyuvm = "0.5.0"
trust_policy = "starter pack must be metadata-validated and imported as reviewable TOML"
supports = ["uvm", "cocotb", "c_header", "spec_trace", "gate"]
```

The pack review rules are in [docs/pack_quality_policy.md](docs/pack_quality_policy.md),
and the local reuse workflow is in [docs/pack_reuse_workflow.md](docs/pack_reuse_workflow.md).
The APB pack includes compatibility metadata, starter `spec_refs`, and local
provenance notes so teams can see which export targets are supported before
replacing pack references with project PDF/spec coordinates during review.
Import pack contents through a reviewable snippet, not an automatic config
rewrite:

```bash
lazyuvm pack install packs/community/apb --maps-out imported_apb.toml
```

Spec/source references for v0.3.x start in
[docs/spec_references.md](docs/spec_references.md); they keep PDF/spec page,
URI, document id, and revision coordinates near reviewed behavior, register,
and field knowledge without turning LazyUVM into a PDF annotation GUI.
Projects can register authoritative documents once with `[spec_sources.*]`,
then cite them from `spec_refs`. Generate the first source-coordinate matrix
with `lazyuvm spec trace --out LazyUVM_Spec_Trace.md`; coverage and gate reports
then surface behavior-level spec origins when coverage holes have reviewed
source context. Reviewed coverage waivers can also carry `spec_refs`, so
accepted gaps show which source requirement is temporarily deferred.
Use `lazyuvm spec coverage --out LazyUVM_Spec_Coverage.md` when reviewers need
one requirement-centered matrix that contrasts source coordinates with linked
coverage holes, accepted waivers, and behavior-only evidence.
Gate reports now roll those links into a Spec Debt Summary for PR review.
Teams can keep this advisory during adoption or enable
`strict_spec_debt = true` / `lazyuvm gate --strict-spec-debt` once orphan or
invalid spec coordinates should block merges.
Use `lazyuvm spec trace --csv --out LazyUVM_Spec_Trace.csv` when reviewers need
a spreadsheet-friendly matrix for external requirements or planning tools.
The boundary is intentional: LazyUVM captures local source coordinates and
CI-readable evidence, while enterprise planning, PDF annotation, and sign-off
remain outside the tool.
The v0.4 export-target direction is documented in
[docs/export_targets.md](docs/export_targets.md). Run `lazyuvm tools targets`
to see the current artifact surface. `lazyuvm regs --c-header --out regs.h`
turns reviewed register maps into a firmware-facing C header, and
`lazyuvm gate --check-c-header regs.h` or `[reports].c_header = "regs.h"` lets
CI catch stale HW/SW register artifacts as part of the normal gate.
`lazyuvm cocotb --out-dir generated_cocotb` generates a local cocotb starter
from the same RTL, protocol, and register knowledge, making LazyUVM useful for
teams that do not start with UVM. `lazyuvm spec --cocotb-plan` then links
behavior specs, spec refs, coverage holes, and accepted waivers into a
reviewable cocotb test plan before anyone commits hand-written tests. Add
`--json` when CI, dashboards, or pack tooling need the same spec-to-cocotb
links as machine-readable evidence. `lazyuvm gate --cocotb-plan-json
.lazyuvm_gate/cocotb_plan.json` attaches that payload to the normal gate
artifacts, and `lazyuvm init-ci --cocotb` adds the starter, plan, JSON evidence,
summary section, uploaded artifact paths, and a guarded Verilator/cocotb smoke
recipe to generated GitHub Actions. Add `--run-cocotb-smoke` when the generated
workflow should execute those Makefiles by default; otherwise set
`LAZYUVM_RUN_COCOTB_SMOKE=1` later once the starter is reviewed for the project.
Vendor-style report fixtures are in
[examples/coverage_reports/](examples/coverage_reports/) with notes in
[docs/eda_report_samples.md](docs/eda_report_samples.md). The v0.3 readiness
checklist is [docs/v0.3_readiness.md](docs/v0.3_readiness.md).
The deeper author workflow is
[docs/team_governance_workflow.md](docs/team_governance_workflow.md). It walks
through coverage holes, reviewable fix drafts, accepted waivers, baseline
deltas, and CI gate evidence as one pull-request workflow. The runnable sample
config is `examples/governance_demo.toml`; run `lazyuvm demo governance` to
print the copy/paste command loop for that sample. For the reviewer side of the
same flow, see
[docs/team_governance_pr_review.md](docs/team_governance_pr_review.md).

## PR Dashboard

The v0.1.9 development cycle makes the pull-request first screen shorter. A
gate report now starts with a compact dashboard before the full reviewer-action
table and step evidence:

```markdown
## PR Dashboard

- Gate: `PASS`
- Top action: blocker - Review newly introduced blocking waiver issues. (`coverage_report.L999`)
- Reproduce / repair: `lazyuvm baseline diff`
- Waiver delta: +2 new, +1 blocking, +1 expiring soon
- Coverage closure: 3 action(s), 0 accepted waiver(s)
- Behavior action: 1 action(s), first `apb_timer.apb_access_completes`
```

Generated `init-ci` workflows lift this section into the GitHub Actions summary
before the longer report. The intent is simple: reviewers should see the gate
state, first action, waiver movement, coverage-closure debt, and first behavior
plan link before scrolling through artifacts.

## Behavior-Driven Plans

The v0.1.7 development cycle connects reviewed behavior specs to the plans a
reviewer needs next: RAL interactions, directed sequences, scoreboard
expectations, and coverage closure stimulus. Try the runnable governance demo:

```bash
lazyuvm spec --config examples/governance_demo.toml --sequence-plan --out LazyUVM_Sequence_Plan.md
lazyuvm regs --config examples/governance_demo.toml --ral-plan --out LazyUVM_RAL_Plan.md
lazyuvm spec --config examples/governance_demo.toml --coverage-plan --out LazyUVM_Coverage_Plan.md
lazyuvm spec --config examples/governance_demo.toml --scoreboard-plan --out LazyUVM_Scoreboard_Plan.md
```

Each behavior plan card shows linked register/field context, related coverage
holes, accepted waivers, review actions, and sequence-level closure ideas for
unwaived holes. The plan remains review-first Markdown; generated starter code
comes after the plan is clear.

## Why This Exists

Research frameworks such as UVLLM and UVMarvel explore ambitious LLM-driven RTL verification flows. Commercial EDA tools own sign-off verification. LazyUVM is deliberately narrower: it targets the local first mile where a student, junior engineer, or small team needs project setup, starter artifacts, reviewed knowledge, and CI evidence in a few minutes.

| Area | Research Frameworks | LazyUVM |
| --- | --- | --- |
| Goal | Broad automated verification research | Local verification bootstrap and knowledge reuse |
| Setup | Larger framework and experiment flow | `pipx install lazyuvm`, then `lazyuvm init` |
| AI | Often benchmarked with large LLM workflows | Optional local Ollama explanations over LazyUVM facts |
| First use | Read paper, configure stack, run experiments | Commit `lazyuvm.toml`, run `lazyuvm gate` |
| Current strength | Full research pipeline | Team-owned protocol/register/spec/pattern knowledge in Git |

LazyUVM is not a replacement for sign-off verification. It is the local layer before that: the place where teams make the first environment, document why checks exist, preserve recurring debug knowledge, and keep CI honest.

For the current package boundary, known limits, and modularization roadmap, see [docs/architecture.md](docs/architecture.md).
For the current v0.1.7 development direction, see
[docs/behavior_driven_plans.md](docs/behavior_driven_plans.md).
For the current v0.1.8 development direction, see
[docs/local_ai_fact_explain.md](docs/local_ai_fact_explain.md).
For the current v0.1.9 development direction, see
[docs/reviewer_action_workflow.md](docs/reviewer_action_workflow.md).
For the v0.2.x adoption and governance direction, see
[docs/legacy_cli_cleanup.md](docs/legacy_cli_cleanup.md),
[docs/v0.3_readiness.md](docs/v0.3_readiness.md), and
[docs/releases/v0.2.9.md](docs/releases/v0.2.9.md).
For the v0.4 export-target direction, see
[docs/export_targets.md](docs/export_targets.md).

## Installation

From a local checkout:

```bash
python3 -m pip install -e .
lazyuvm --version
lazyuvm --help
lazyuvm legacy --help  # advanced one-off scan flags
```

From the current `main` branch:

```bash
pipx install git+https://github.com/jeonghunx/LazyUVM.git
```

From PyPI's latest release:

```bash
pipx install lazyuvm
```

Contributors can still run `python3 rtl_scout.py ...` directly from the repository for compatibility, but `lazyuvm ...` is the preferred CLI.
Top-level `lazyuvm --help` shows the project-command workflow. Use
`lazyuvm legacy --help` only when you need the older direct flags such as
`--tb-dir`, `--uvm-dir`, `--analyze-log`, or `--analyze-coverage`.
Use `lazyuvm <command> --help` or `lazyuvm help <command>` for detailed command
options.
Calling those direct flags without the `legacy` subcommand now prints a
deprecation warning to stderr. The flags still work for compatibility, but new
automation should prefer `lazyuvm.toml` plus project commands such as
`lazyuvm check`, `lazyuvm uvm`, and `lazyuvm gate`.

## Migrating From Old Direct Flags

If an older script starts with bare flags such as `lazyuvm --filelist ...`,
`lazyuvm --analyze-log ...`, or `lazyuvm --cache-review ...`, it still works
for now and prints a warning. For repeatable project work, migrate it to the
project-command surface:

```bash
# Old one-off shape
lazyuvm --filelist files.f --checks

# Preferred v0.2.x project shape
lazyuvm init --filelist files.f --top your_top
lazyuvm check
lazyuvm gate --update-manifest
```

Use `lazyuvm legacy ...` only when you intentionally need the old one-off
scanner behavior. For concrete before/after examples covering checks, log
triage, pattern packs, coverage closure, and CI, see
[docs/legacy_cli_cleanup.md](docs/legacy_cli_cleanup.md).
You can also print the short terminal version:

```bash
lazyuvm demo migration
```

## Release Status

Current repository version: `0.5.2`

Latest tagged release: `0.5.2`

Latest PyPI release: verify with `python3 -m pip index versions lazyuvm`

- See `CHANGELOG.md` for the release history.
- See `RELEASE_CHECKLIST.md` before cutting a tag.
- See `docs/releases/v0.5.2.md` for the latest tagged release note.
- The GitHub Actions badge should be green before cutting a release tag.
- PyPI publishing is configured through `.github/workflows/release.yml` and PyPI Trusted Publishing.

## Quick Start

From a checkout of the current `main` branch:

```bash
cd "/mnt/c/Users/jeonghun-dev/Documents/New project"

lazyuvm --version
lazyuvm check
lazyuvm report
lazyuvm regress
lazyuvm uvm
lazyuvm baseline save
lazyuvm baseline diff
lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --no-ai
```

`lazyuvm init` writes a project-owned `lazyuvm.toml`. Commit that file so teammates and CI can run the same local verification flow without copying long command lines.

For a new RTL project:

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

For a new GitHub project that should get the full LazyUVM workflow:

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

The generated workflow installs LazyUVM from the package source passed with `--package`. The default is the PyPI package, `lazyuvm`. During unreleased development, pass a Git URL if you intentionally want CI to install from a branch.
Use `--run-cocotb-smoke` only after the generated cocotb starter has been
reviewed against the project's simulator assumptions.

The sections below prefer project commands. Legacy direct-flag examples are
called out explicitly and can be run with `lazyuvm legacy ...` when you need a
one-off scan outside a configured project.

## Project Config

`lazyuvm.toml` is the sticky project entry point:

```toml
[project]
filelist = "examples/files.f"
top = "apb_timer"
no_ai = true
ollama_model = "llama3.2:1b"
ai_timeout = 60
no_lint = false

[reports]
auto_dir = ".lazyuvm"
report = "LazyUVM_Report.md"
regress_file = "examples/regress.yaml"
regress_dir = ".lazyuvm_regress"
regress_report = "LazyUVM_Regression.md"
uvm_dir = "generated_uvm"
seeds = "1"
baseline = "lazyuvm_baseline.json"
coverage_report = "examples/coverage_report.txt"
coverage_threshold = 90.0
c_header = "regs.h"
c_header_prefix = "LAZYUVM"

[registry]
cache_dir = ".lazyuvm_cache"
registry_dir = ".lazyuvm_registry"

[knowledge]
strict_modules = ["apb_timer", "axi_lite_gpio"]
strict_checks = ["missing_protocol_maps", "missing_register_maps", "no_reviewed_patterns"]
strict_require_registry_bundles = false
explain_query = "apb timeout"

[knowledge.trace]
ignored_signals = ["clk", "pclk", "aclk", "reset", "resetn", "rst_n", "presetn", "aresetn"]
min_pattern_signal_overlap = 2

[behaviors.apb_timer.apb_access_completes]
description = "APB access must eventually complete once setup/access is active"
protocol = "APB"
trigger = "psel && penable"
expect = "pready"
within_cycles = 16
severity = "error"
registers = ["counter"]
fields = ["counter.value"]
```

Once the config is committed, the project workflow becomes short and repeatable:

```bash
lazyuvm check     # hierarchy + static RTL checks
lazyuvm report    # auto-run + Markdown report
lazyuvm regress   # regress.yaml or seed regression
lazyuvm uvm       # generated UVM/SVA/coverage/bind skeletons
lazyuvm spec      # validate behavior/spec intent maps
lazyuvm regs --ral-plan --out LazyUVM_RAL_Plan.md
lazyuvm spec --ral-plan --out LazyUVM_RAL_Plan.md
lazyuvm spec --plan --out LazyUVM_Spec_Plan.md
lazyuvm spec --sequence-plan --out LazyUVM_Sequence_Plan.md
lazyuvm spec --coverage-plan --out LazyUVM_Coverage_Plan.md
lazyuvm spec --scoreboard-plan --out LazyUVM_Scoreboard_Plan.md
lazyuvm spec --sva-dir generated_specs
lazyuvm spec --sequence-dir generated_sequences
lazyuvm spec --coverage-dir generated_behavior_coverage
lazyuvm baseline save
lazyuvm baseline diff
lazyuvm pack stats
lazyuvm know trace --out LazyUVM_Traceability.md
lazyuvm know trace --json --out LazyUVM_Traceability.json
lazyuvm know manifest --out LazyUVM_Knowledge_Manifest.json
lazyuvm know manifest-verify LazyUVM_Knowledge_Manifest.json
lazyuvm know query "apb timeout"
lazyuvm know recommend
lazyuvm gate --update-manifest --json-out LazyUVM_Gate.json
```

The reviewable knowledge formats behind this workflow are documented in
[`docs/knowledge_formats.md`](docs/knowledge_formats.md).

`lazyuvm know trace` filters pattern links with `[knowledge.trace]`. Keep the
default clock/reset ignores, raise `min_pattern_signal_overlap`, or add noisy
project-wide handshakes to `ignored_signals` when traceability rows are being
linked by generic signals instead of useful debug evidence.
Use `--json` when CI jobs, dashboards, or local-AI workflows need the same
traceability matrix as a stable `lazyuvm.traceability.v1` payload.
`lazyuvm know manifest` fingerprints the current project knowledge sources
(`lazyuvm.toml`, local pattern cache, registry index) and records knowledge
counts plus traceability summary as a `lazyuvm.knowledge_manifest.v1` payload.
`lazyuvm know manifest-verify` checks that saved snapshot against the current
local files, counts, and traceability settings so CI can catch stale knowledge
manifests before review.

`lazyuvm know query` is the first knowledge-workflow command: it groups matching
protocol maps, register/spec maps, reviewed patterns, packs, and bundles for one
local question. It does not upload project data or ask an AI by default:

```bash
lazyuvm know query "pready never asserted"
lazyuvm know query "ctrl enable" --out LazyUVM_Knowledge_Query.md
lazyuvm know explain "apb timeout"
lazyuvm know explain "apb timeout" --ai --out LazyUVM_Knowledge_Explain.md
lazyuvm know explain "coverage closure" --gate-json LazyUVM_Gate.json --json --out LazyUVM_Knowledge_Explain.json
lazyuvm know recommend --out LazyUVM_Knowledge_Recommend.md
lazyuvm know recommend --json --out LazyUVM_Knowledge_Recommend.json
lazyuvm know recommend --strict --module apb_timer
lazyuvm know doctor --strict
```

`know explain` keeps the trust boundary explicit: LazyUVM finds local facts from
maps, reviewed patterns, packs, bundles, coverage trace, waivers, behavior plan
cards, and optionally a `lazyuvm.gate.v1` JSON artifact; optional `--ai` asks
local Ollama to turn those facts into a readable debug note. The AI output is a
reading aid, not a verified root-cause diagnosis.
Use `--json` when CI jobs, dashboards, or future local-AI workflows need the same
facts as a stable `lazyuvm.knowledge_explain.v1` payload.
Generated `lazyuvm init-ci` workflows upload both explain and recommend reports
as Markdown/JSON artifacts so project knowledge can be reviewed without scraping
terminal logs.

Use `--strict` when CI should fail on missing core project knowledge such as
protocol maps, register maps, or reviewed patterns. Registry bundles are reported
as recommendations, but they are not strict blockers by default. Projects can
pin that policy in `[knowledge]`: use `strict_modules` to limit the enforced
entry points, `strict_checks` to choose blocker recommendation codes, and
`strict_require_registry_bundles = true` when a team bundle is mandatory.
`know recommend --strict` and `know doctor --strict` use the same policy so local
diagnostics and CI gates agree.

The repository includes a portable example bundle:

```bash
lazyuvm pack bundle-validate examples/team_knowledge_bundle.json
lazyuvm pack bundle-import examples/team_knowledge_bundle.json --maps-out lazyuvm_imported_maps.toml
```

For the full local publish/pull loop, see
[`docs/team_registry_demo.md`](docs/team_registry_demo.md).

The checked GitHub Actions workflow also smoke-tests this knowledge loop by
validating the example bundle, running `know query` / `know recommend`, uploading
the Markdown and JSON recommendation reports as an artifact, writing a short
baseline/knowledge summary to the GitHub Actions run summary, and round-tripping
a bundle through a temporary self-hosted registry.

## Custom Protocol Maps

LazyUVM first tries protocol inference from familiar names such as `psel`, `penable`, and `awvalid`. Real projects often use names like `cfg_sel`, `cfg_enable`, or `cfg_ack`. Add a `[protocols.<module>]` section to `lazyuvm.toml` when a module uses project-specific naming:

```toml
[protocols.cfg_timer]
protocol = "APB"
pclk = "clk"
presetn = "rst_n"
paddr = "cfg_addr"
psel = "cfg_sel"
penable = "cfg_enable"
pwrite = "cfg_write"
pwdata = "cfg_wdata"
prdata = "cfg_rdata"
pready = "cfg_ack"
pslverr = "cfg_err"
```

Then run the normal project command:

```bash
lazyuvm uvm --config examples/custom_protocols.toml --uvm-dir /tmp/lazyuvm_custom_uvm
```

Generated UVM/SVA/coverage files use the real project port names while keeping the APB starter behavior. This is explicit project mapping, not semantic protocol discovery.

`lazyuvm check`, `lazyuvm report`, `lazyuvm regress`, `lazyuvm baseline`, and `lazyuvm uvm` validate these maps before trusting them. Missing required protocol signals, unknown canonical keys, and mapped ports that do not exist in the RTL are reported as errors.

To draft a map for custom names, use the suggestion command:

```bash
lazyuvm suggest-protocol-map examples/cfg_timer.sv --module cfg_timer --out suggested_protocols.toml
lazyuvm suggest-protocol-map --config examples/custom_protocols.toml --out suggested_protocols.toml
```

The output is a reviewable TOML snippet with per-signal confidence comments. It is not applied automatically; merge it into `lazyuvm.toml` only after review and validation.

## Register/Spec Maps

Protocol maps explain how project-specific port names map onto APB/AXI-style signals. Register/spec maps explain what project registers mean. This is how LazyUVM avoids pretending that AI inferred `ctrl[0] = enable`; the team writes that knowledge once and commits it:

```toml
[registers.cfg_timer.timer_value]
address = "0x00"
width = 32
access = "rw"
reset = "0x00000000"
description = "Timer value register"

[fields.cfg_timer.timer_value.value]
bits = "31:0"
access = "rw"
reset = "0x00000000"
description = "Current timer value"
```

Validate and print the map:

```bash
lazyuvm regs --config examples/custom_protocols.toml
```

To draft a register/spec map from obvious signal names, use:

```bash
lazyuvm suggest-register-map examples/cfg_timer.sv --module cfg_timer --out suggested_registers.toml
```

The output is also review-first. LazyUVM may suggest `timer_value` as a register candidate, but address and reset facts remain `TODO` until the team checks the spec. Merge the snippet only after review, then run `lazyuvm regs` and `lazyuvm check`.

`lazyuvm check` and `lazyuvm baseline save` also validate register/spec maps, so broken team knowledge fails early instead of silently feeding bad generated artifacts.

## Artifact Quality Gate

`lazyuvm quality` generates the UVM/SVA/coverage starter set into a quality workspace and checks that the artifact set is complete and structurally sane:

```bash
lazyuvm quality --config examples/custom_protocols.toml
```

It verifies required files, package includes, filelist references, missing-signal placeholders, TODO/FIXME markers, and balanced SystemVerilog structures such as `module`/`endmodule`, `class`/`endclass`, and `task`/`endtask`.

The same report now includes a knowledge recommendation summary so CI reviewers can see protocol-map, register-map, reviewed-pattern, and bundle gaps next to artifact quality findings.

This is a local CI smoke gate for generated starters. It does not claim to replace a commercial simulator compiling full UVM with a vendor library. Use `--strict` when you want warnings to fail CI too.

## Project Gate

`lazyuvm gate` is the team-facing entry point for the local verification
knowledge workflow. It combines project input checks, protocol/register/behavior
map validation, generated-artifact quality, strict knowledge policy, pattern
pack validation, knowledge manifest verification, and configured coverage triage
into one Markdown/JSON report:

```bash
lazyuvm gate
lazyuvm gate --strict --manifest LazyUVM_Knowledge_Manifest.json
lazyuvm gate --update-manifest --json-out LazyUVM_Gate.json
```

Use `--update-manifest` when intentionally refreshing the reviewed project
knowledge snapshot. In CI, use `--strict` with a committed manifest when you
want changes to `lazyuvm.toml`, reviewed patterns, registry state, or
traceability settings to fail until the team updates the snapshot deliberately.

## Team Knowledge Bundles

LazyUVM's moat is reviewed local knowledge, not secret telemetry. A team can export protocol maps, register/spec maps, and reviewed pattern cache entries as one portable bundle:

```bash
lazyuvm pack --config examples/custom_protocols.toml bundle-export team_cfg_timer_bundle.json
lazyuvm pack bundle-validate team_cfg_timer_bundle.json
lazyuvm pack manifest team_cfg_timer_bundle.json --out team_cfg_timer_bundle.manifest.json
lazyuvm pack manifest-verify team_cfg_timer_bundle.manifest.json --artifact team_cfg_timer_bundle.json
lazyuvm pack bundle-import team_cfg_timer_bundle.json --maps-out lazyuvm_imported_maps.toml
lazyuvm pack bundle-diff old_bundle.json team_cfg_timer_bundle.json
```

Importing a bundle merges reviewed patterns into the local cache, but it does not silently edit `lazyuvm.toml`. Protocol/register map sections are written to a reviewable TOML snippet so a human can inspect them before merging.
`lazyuvm pack manifest` writes a `lazyuvm.trust_manifest.v1` JSON sidecar with
the artifact SHA-256 digest, LazyUVM version, current git commit, and review
policy. It is provenance metadata, not a cryptographic signature.
`lazyuvm pack manifest-verify` checks that the current artifact still matches
the recorded digest and size, making the manifest usable as a lightweight CI
gate.

Self-hosted teams can publish and pull bundles through the file-based registry:

```bash
lazyuvm pack --config examples/custom_protocols.toml bundle-publish cfg_timer_basics
lazyuvm pack bundle-pull cfg_timer_basics --maps-out lazyuvm_imported_maps.toml
```

Search the accumulated local knowledge without opening every JSON/TOML file by hand:

```bash
lazyuvm know search apb timeout
lazyuvm know show protocols.cfg_timer
lazyuvm know doctor
```

## CI Bootstrap

`lazyuvm init-ci` creates the files a project needs to make LazyUVM part of the normal team workflow:

```text
lazyuvm.toml
regress.yaml
LAZYUVM_BADGE.md
.github/workflows/lazyuvm.yml
```

The generated workflow installs LazyUVM from the package source passed with `--package`, runs `lazyuvm check`, `lazyuvm report`, `lazyuvm regress`, validates the local pattern-pack state, and then compares against `lazyuvm_baseline.json` when one exists. If no baseline exists yet, CI saves an initial one for that run so the workflow can pass before the team commits a reviewed baseline. Add `--strict-knowledge` when the generated workflow should fail on the configured `[knowledge]` policy from day one.

Baseline snapshots also track local knowledge counts such as protocol maps, register maps, fields, reviewed patterns, and registry bundles. That makes `lazyuvm baseline diff` show whether the team's reusable verification memory is growing along with the RTL checks.

Use `--force` only when you intentionally want to overwrite generated files.

## Team Pattern Packs

`lazyuvm pack` is the product-style workflow for team-reviewed local bug patterns. It uses the `[registry]` paths in `lazyuvm.toml`, so teams can share trusted patterns without any external service:

```bash
lazyuvm pack report
lazyuvm pack search paddr
lazyuvm pack show b5064cf
lazyuvm pack review b5064cf --note "APB setup/access timeout seen in smoke regressions"
lazyuvm pack export team_apb_patterns.json
lazyuvm pack import team_apb_patterns.json
lazyuvm pack publish apb_smoke
lazyuvm pack list
lazyuvm pack pull apb_smoke
lazyuvm pack validate
lazyuvm pack doctor --strict
lazyuvm pack doctor
```

By default, `lazyuvm pack export` exports only reviewed entries. Use `--all` when you deliberately want a raw cache backup.
Use `pack validate` before publishing or sharing a team pack. It checks for empty packs, missing metadata, unreviewed registry entries, and reviewed entries without review notes.
Use `pack doctor --strict` in CI when you want the same health check to fail on validation issues. Use plain `pack doctor` when a teammate says their cache or shared registry is not behaving as expected.

Generated files appear under:

```text
generated_uvm/apb_timer/
```

The UVM generator now also writes assertion and coverage sentinels:

```text
generated_uvm/apb_timer/lazyuvm_apb_timer_sva.sv
generated_uvm/apb_timer/lazyuvm_apb_timer_coverage.sv
generated_uvm/apb_timer/lazyuvm_apb_timer_bind.sv
generated_uvm/axi_lite_gpio/lazyuvm_axi_lite_gpio_sva.sv
generated_uvm/axi_lite_gpio/lazyuvm_axi_lite_gpio_coverage.sv
generated_uvm/axi_lite_gpio/lazyuvm_axi_lite_gpio_bind.sv
```

The bind files use SystemVerilog `bind` plus implicit port connections, so the generated sentinels can be attached to the DUT without editing the original RTL.

Generated outputs are ignored by Git because they can be recreated at any time.

## Filelist Project Linker

Real RTL projects often compile from a `files.f` file instead of a single source path. LazyUVM can now use that same project entry point:

```bash
lazyuvm init --filelist examples/files.f --top apb_timer
lazyuvm check
lazyuvm report
```

Supported filelist syntax:

```text
+incdir+include
+define+SIMULATION
+define+WIDTH=32
-f nested_files.f
rtl/top.sv
rtl/block.sv
```

File paths and nested filelists are resolved relative to the filelist that mentions them. `lazyuvm report` passes include dirs and defines through to Verilator and Icarus Verilog, then records the exact reproduce commands in the Markdown report.

## Tool Command Generator

LazyUVM can turn a project filelist into copy/paste commands for common RTL tools without launching licensed software:

```bash
lazyuvm tools emit verilator
lazyuvm tools emit vcs
lazyuvm tools emit questa
```

Example output:

```bash
verilator --lint-only --sv -f examples/files.f
vcs -sverilog -full64 -f examples/files.f
vlog -sv -f examples/files.f
```

The project command reads `lazyuvm.toml`, so the filelist, include dirs, defines,
and default top/module stay in one reviewable place. When you pass `--module`,
LazyUVM treats it as the top/module hint:

```bash
lazyuvm tools emit verilator --module chip_top
lazyuvm tools emit vcs --module chip_top
lazyuvm tools emit questa --module chip_top
```

For a one-off command outside a configured project, the legacy compatibility
surface still exists:

```bash
lazyuvm legacy --filelist examples/files.f --emit-tool verilator
```

## Regression Runner

For a small local regression:

```bash
lazyuvm regress --seeds 1,2,3 --no-ai
```

This writes:

```text
LazyUVM_Regression.md
.lazyuvm_regress/
```

The regression runner:

- generates a smoke testbench for each selected module
- passes `+LAZYUVM_SEED=<seed>` into `vvp`
- repeats each module across the requested seed list
- keeps each case in its own workspace folder
- records lint, compile, simulation, and overall PASS/FAIL status in a Markdown matrix

Seed ranges are supported:

```bash
lazyuvm regress --seeds 1-10 --module chip_top --no-ai
```

This is still an early screening loop, not signoff. Its job is to make local smoke regressions cheap enough to run constantly.

For a project-owned regression plan:

```bash
lazyuvm init --filelist examples/files.f --top apb_timer --regress-file examples/regress.yaml
lazyuvm regress --no-ai
```

Example `regress.yaml`:

```yaml
tests:
  - name: apb_smoke
    files: files.f
    module: apb_timer
    seeds: 1,2

  - name: axi_smoke
    files: files.f
    module: axi_lite_gpio
    seeds: 1,2
```

Paths in the YAML file are resolved relative to that YAML file, so a test plan under `examples/` can simply use `files: files.f`.

Supported keys:

- `name`: test name shown in reports
- `files` or `filelist`: one filelist path or a short list
- `module` or `top`: module to run
- `seeds`: comma list or range such as `1,2,3` or `1-10`

## Coverage Triage

For a configured project, prefer the knowledge workflow. Put the coverage report
path under `[reports].coverage_report`, then run:

```bash
lazyuvm know coverage --out LazyUVM_Coverage_Trace.md
lazyuvm gate --coverage-report examples/coverage_report.txt --json-out LazyUVM_Gate.json
```

For a one-off text coverage report outside a configured project, use the legacy
compatibility surface:

```bash
lazyuvm legacy --analyze-coverage examples/coverage_report.txt --no-ai
```

LazyUVM extracts:

- coverage percentages such as line, branch, toggle, and functional coverage
- common vendor-style table rows with covered/total/percent columns
- ratio-only rows such as `0/1` when the row looks like coverage data
- low coverage metrics below a threshold
- explicit miss lines such as `0 hits`, `Hits: 0`, `Count = 0`, `uncovered`, `not covered`, and `never hit`
- rule-based next stimulus ideas for APB, AXI-Lite, reset, FSM, and toggle holes

To change the low-coverage threshold:

```bash
lazyuvm legacy --analyze-coverage examples/coverage_report.txt --coverage-threshold 80 --no-ai
```

To write the analysis to a file:

```bash
lazyuvm legacy --analyze-coverage examples/coverage_report.txt --coverage-md LazyUVM_Coverage.md --no-ai
lazyuvm legacy --analyze-coverage examples/vendor_coverage_report.txt --coverage-json LazyUVM_Coverage.json --no-ai
```

The JSON output uses the `lazyuvm.coverage_analysis.v1` schema and contains
parsed metrics, low/missing coverage items, and deterministic next-stimulus
ideas so CI, dashboards, or local-AI workflows can consume coverage facts
without scraping Markdown.

With Ollama available, omit `--no-ai` to add a local summary on top of the rule-based findings.

To generate starter SystemVerilog stimulus tasks from the same coverage holes:

```bash
lazyuvm legacy --analyze-coverage examples/coverage_report.txt --coverage-stimulus-dir generated_stimulus --module apb_timer --no-ai
lazyuvm legacy --analyze-coverage examples/vendor_coverage_report.txt --coverage-stimulus-dir generated_stimulus --module apb_timer --no-ai
```

This writes a skeleton such as:

```text
generated_stimulus/lazyuvm_apb_timer_coverage_stimulus.sv
```

The generated file contains task stubs for holes such as APB wait states, AXI-Lite backpressure, reset edges, toggles, and generic directed bins. It also records parsed targets such as source locations, coverpoints, bins, branch conditions, and likely protocol signals. It intentionally leaves BFM/UVM calls as TODO comments because real projects name their sequence APIs differently.

## Hierarchy Scan

For configured projects, `lazyuvm check` prints hierarchy and top-candidate
context as part of the local health check:

```bash
lazyuvm check
```

For a one-off folder scan, use the legacy compatibility surface:

```bash
lazyuvm legacy --hierarchy examples
lazyuvm legacy --hierarchy --module chip_top examples
```

This prints top-module candidates and a simple instance tree, for example:

```text
chip_top [AXI-Lite 95%, APB 80%]
|-- apb_timer u_timer [APB 90%]
`-- axi_lite_gpio u_gpio [AXI-Lite 100%]
```

## Width Solver

For configured projects, `lazyuvm check` includes lightweight width solving when
it can infer enough local context. For a one-off parameterized design:

```bash
lazyuvm legacy --widths examples/axi_lite_gpio.sv
```

This resolves simple integer expressions in packed ranges:

```text
axi_lite_gpio:
  parameters:
    ADDR_WIDTH = 12 => 12
    DATA_WIDTH = 32 => 32
  ports:
    input awaddr: [ADDR_WIDTH-1:0] => 12 bits
    input wstrb: [(DATA_WIDTH/8)-1:0] => 4 bits
```

## Static Checks

For a quick local RTL review:

```bash
lazyuvm check
```

LazyUVM checks what it can prove from the local source:

- unresolved module instances
- unconnected named child ports
- obvious parent/child port width mismatches
- clock-like modules without reset-like inputs
- reset-like ports with suspicious directions

These checks are intentionally conservative: if LazyUVM cannot infer a width confidently, it avoids guessing a mismatch.

## Auto-Run Report

For a one-command local triage loop:

```bash
lazyuvm report
```

This writes:

```text
LazyUVM_Report.md
.lazyuvm/
```

The auto-run loop:

- scans the RTL
- runs lightweight static RTL checks
- generates a starter testbench
- generates UVM skeleton files
- lints the RTL with Verilator when available
- compiles with `iverilog`
- runs with `vvp`
- triages lint/compile/simulation logs
- optionally asks local Ollama for an explanation
- writes patch suggestions under `.lazyuvm/patches/`

If Verilator is not installed or you only want the simulator path:

```bash
lazyuvm report --no-lint
```

Safety rule: LazyUVM does not modify your RTL source files during auto-run. Patch suggestions are isolated for manual review.

## Local AI Log Analysis

AI is optional. The rule-based analyzer works without Ollama:

```bash
lazyuvm triage --log examples/sim_error.log --no-ai
lazyuvm triage --log examples/timing_trace.log --no-ai
```

The log analyzer extracts suspicious lines and a compact timeline before local AI is used:

```text
Timeline:
  100ns L3 [event] signals: psel=1, penable=0, pwrite=1
  120ns L5 [error] signals: penable=1, penable=0, psel=1, pready=0
  130ns L7 [fatal] signals: psel=1, penable=0, pready=0
```

With Ollama:

```bash
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.2:1b

lazyuvm triage --log examples/sim_error.log --ai --ollama-model llama3.2:1b
```

## Spec-Aware Log Cross-Check

For a small spec/log comparison:

```bash
lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --no-ai
```

LazyUVM extracts simple requirement lines containing words such as `must`, `shall`, `within N cycles`, `after reset`, and `remain high until`, then compares the supported rules against the log timeline.

Example requirement:

```text
PENABLE must assert one cycle after PSEL is asserted.
PSEL must remain high until PREADY.
```

The checker is intentionally conservative. It reports direct evidence from the timeline, for example:

```text
Spec expects `penable` after `psel`, but timeline never shows `penable=1` before the failure evidence.
```

This is a fact cross-check, not a full natural-language spec verifier.

## Local Pattern Cache

LazyUVM does not upload project data. By default, it only prints analysis results. If you explicitly add `--learn-cache`, it stores a small local pattern entry under `.lazyuvm_cache/patterns.json`.

```bash
lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --learn-cache --no-ai
lazyuvm legacy --analyze-coverage examples/coverage_report.txt --learn-cache --no-ai
lazyuvm pack report
```

After patterns are learned, use `--use-cache` to compare the current log or coverage report with the local project memory:

```bash
lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --no-ai
lazyuvm legacy --analyze-coverage examples/coverage_report.txt --use-cache --no-ai
```

For a shareable Markdown debug report, use pattern-aware triage:

```bash
lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --no-ai
lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --ai
```

The first command is fully rule-based. The second command adds a local Ollama summary when a model is available. In both cases, LazyUVM uses extracted log facts and local pattern-pack matches as evidence; pattern matches are prior debugging memory, not proof.

After a human confirms the issue, close the debug-to-pack loop in one command:

```bash
lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --learn-reviewed --note "confirmed APB setup/access timeout" --no-ai
lazyuvm pack show b5064cf
```

`--learn-reviewed` stores the current pattern and marks it reviewed immediately. Use it only after someone has checked the evidence.

The cache keeps normalized fingerprints, categories, repeated-hit counts, signal names found in timelines, and short rule-based hints. Cache matching uses local fingerprints plus category, signal, and hint-token overlap. It is meant to become a private project memory, not hidden telemetry.

Use a custom cache folder when you want to keep experiments separate:

```bash
lazyuvm triage --log examples/timing_trace.log --learn-cache --cache-dir /tmp/lazyuvm_cache --no-ai
lazyuvm triage --log examples/timing_trace.log --use-pack --cache-dir /tmp/lazyuvm_cache --no-ai
```

For team sharing without a central server, export and import the cache as a plain JSON file:

```bash
lazyuvm pack export lazyuvm_patterns.json
lazyuvm pack import lazyuvm_patterns.json
lazyuvm pack report
```

Import merges by fingerprint. Re-importing the same file updates matching entries instead of duplicating them, so teams can pass around a reviewed pattern pack in source control, chat, or an internal artifact store.

For a reviewed team pattern pack, mark only trusted entries before exporting:

```bash
lazyuvm pack report
lazyuvm pack review b5064cf --note "APB setup/access timeout seen in smoke regressions"
lazyuvm pack export lazyuvm_reviewed_patterns.json
lazyuvm pack import lazyuvm_reviewed_patterns.json
```

The shorter project workflow is preferred once `lazyuvm.toml` exists:

```bash
lazyuvm pack report
lazyuvm pack search paddr
lazyuvm pack show b5064cf
lazyuvm pack review b5064cf --note "APB setup/access timeout seen in smoke regressions"
lazyuvm pack export lazyuvm_reviewed_patterns.json
lazyuvm pack import lazyuvm_reviewed_patterns.json
lazyuvm pack validate
```

`pack review` and `pack unreview` accept unique fingerprint prefixes, so you do not need to type the full hash.

For a self-hosted team registry, publish reviewed packs into a shared folder:

```bash
lazyuvm pack --registry-dir /shared/lazyuvm_registry publish apb_smoke
lazyuvm pack --registry-dir /shared/lazyuvm_registry list
lazyuvm pack --registry-dir /shared/lazyuvm_registry pull apb_smoke
```

With `lazyuvm.toml`, use the product commands:

```bash
lazyuvm pack publish apb_smoke
lazyuvm pack list
lazyuvm pack pull apb_smoke
lazyuvm pack doctor --strict
```

The registry is just files:

```text
lazyuvm_registry.json
packs/apb_smoke.json
```

That makes it usable with an internal Git repo, shared drive, artifact store, or any company-controlled file server. No external service is required.

As the cache grows, inspect and prune it:

```bash
lazyuvm pack stats
lazyuvm pack prune 100
lazyuvm pack stats
```

Pruning keeps the highest-count and most recently seen entries first. Use export before pruning if you want a backup:

```bash
lazyuvm pack export lazyuvm_patterns_backup.json
lazyuvm pack prune 100
```

## License

LazyUVM is released under GPLv3. Commercial licensing can be considered separately for companies that need different terms.

This is not legal advice; talk to a lawyer before using any open-source license strategy commercially.
