Rtl Acquire

rtl-acquire — the RTL corpus supplier

Execute a staged, artifact-first corpus-expansion workflow for discovered RTL: acquire → expand (synth-only) → repair → validate → publish. Prefer deterministic scripts and policy files; treat the workspace ledgers and manifests as the source of truth.

Positioned upstream of the other r2g-skills: it feeds a stream of screened, synthesized, graph-converted designs. It never runs place/route or signoff — hand a promising design to signoff-loop for that.

The scoped-reuse contract (what this skill OWNS vs BORROWS)

OWNS (the heart — genuinely net-new for r2g):

• acquire/ — discovery/search/clone/screen of candidate RTL at corpus scale

(local _downloads trees, repo manifests, keyword search), RAM/macro exclusion, bundle-aware candidate CSVs, incremental scan ledgers.

• corpus hygiene + publish — rtl/netlist signature dedup, repo/design

quality scoring, publish eligibility gating, the merged corpus manifest.

• repair/ — deterministic frontend repair (include dirs, stubs, memory

limits, template materialization) + the JSON failure casebook (journal-side).

BORROWS (converged onto sibling sub-skills — never reimplement these here):

• env/toolchain — the shared byte-identical scripts/flow/_env.sh +

references/env.local.sh pin written by eda-install (skill_env.py is a thin delegate over it).

• ORFS synthesis — signoff-loop/scripts/flow/run_orfs.sh with

ORFS_STAGES=synth (per-candidate project dirs; the r2g Hard Rules hold by construction).

• graph format — def-graph/scripts/extract/graph/netlist_graph.py

produces every corpus graph (netlist_graph.pt); the legacy 30pt converter is retired (2026-07-09 amendment).

• failure learning — every flow ingests into signoff-loop's

knowledge/knowledge.sqlite (R2G_FLOW_SCOPE = synth_only); frontend failure classes land as synth-frontend- failure_events.

Default Paths (all overridable, R2G_ACQUIRE_*)

• acquire root: /design_cases/_rtl_acquire (R2G_ACQUIRE_ROOT)
• downloads root: $R2G_ACQUIRE_ROOT/_downloads (R2G_ACQUIRE_DOWNLOADS)
• workspace: $R2G_ACQUIRE_ROOT/workspace (R2G_ACQUIRE_WORKSPACE)
• candidates/ scan_state/ failures/ quality/ audits/ runs/

manifests/ — the ledger surfaces

• synth_projects// — per-candidate ORFS project dirs

(constraints/config.mk + constraint.sdc + backend/ + reports/)

• corpus (success root): $R2G_ACQUIRE_ROOT/corpus (R2G_ACQUIRE_OUT) —

per-design netlist_graph.pt, mapped_netlist.v, cell_stats.json, design_meta.json, plus index.csv + _design_status/

• ORFS seed corpus (optional): $R2G_ACQUIRE_ROOT/orfs_seed_designs

(R2G_ACQUIRE_SEED_ROOT)

• merged manifest: $R2G_ACQUIRE_ROOT/netlist_graph_corpus_manifest.csv

(R2G_ACQUIRE_MERGED_MANIFEST)

Environment Resolution

Never hand-configure tools here. Resolution order (same as every r2g skill): shell env > $R2G_ENV_FILE > references/env.local.sh (written by eda-install's write_env_local.sh) > _env.sh autodetection. Verify with python3 scripts/skill_env.py (prints every resolved root/tool) or the comprehensive signoff-loop/scripts/flow/check_env.sh.

Knobs specific to this skill:

• R2G_ACQUIRE_PLATFORM — target ORFS platform (default nangate45; v1 scope)
• R2G_ACQUIRE_SYNTH_TIMEOUT — per-candidate synth timeout s (default 3600)
• R2G_ACQUIRE_NUM_CORES — cap ORFS NUM_CORES per flow (Hard Rule:

concurrent flows × cores ≈ machine cores)

• R2G_GRAPH_PYTHON — torch venv for graph conversion + scale reports; when

unset those stages SKIP with a HINT and designs record graph_skipped (never success)

• R2G_KNOWLEDGE_DB — override the knowledge DB (tests only; default is the

committed signoff-loop store)

• R2G_ACQUIRE_ENABLE_LLM=1 — opt-in for the LLM patch path (default OFF)

Mandatory Stage Order

1. Acquire

Gather candidate RTL from _downloads, repo manifests, or prebuilt CSVs.

• scripts/acquire/discover_download_candidates.py
• scripts/acquire/discover_repo_manifest_candidates.py
• scripts/acquire/clone_repo_manifest.py

Outputs: candidate CSV + updated scan_state/downloads_scan_state.json.

RAM/hard-macro keywords are risk markers, never hard rejects (2026-07-10; the old whole-text substring reject threw picorv32 away on its formal-only RISCV_FORMAL_BLACKBOX_* macro names): tokenized + comment-stripped matching lives in scripts/common/rtl_risk.py, the flags ride the candidate notes column (risk_flags=…), and the synth attempt is the real arbiter — a true hard-macro dependency fails with evidence and the repair-side classifier excludes it then. --retry-excluded re-emits candidates parked in failed_candidates_exclude.csv (a past failure must not permanently block a retry after a fix).

2. Expand (synth-only, converged)

scripts/execute/expand_candidates.py per candidate: sanitize RTL (encoding, helper modules, iscas89 dff) → write synth_projects// → synth via runorfs.sh (ORFS_STAGES=synth, FLOWVARIANT = the unique candidate id) → sv2v/vhd2vl fallback + LEC-lite when needed → dedup by rtl/netlist signature → convert via def-graph netlist_graph.py → cell_stats.json (liberty-driven seq/comb split) → ingest into knowledge.sqlite (every flow, pass or fail). Outputs: corpus dir updates, refreshed index.csv, _design_status/.

Failed candidates in the index always retry on the next run (only status==success skips); --force re-runs successes too (regeneration after a synth/extractor fix). Candidate paths are CWD-proof: ~/$VAR expand, and relative paths bind to the candidate CSV's directory, then the repo root — never the caller's CWD (see references/candidate_csv_schema.md).

3. Repair

• scripts/repair/classify_failed_candidates.py → retry vs exclude + class
• scripts/repair/auto_fix_failures.py (deterministic first-line)
• scripts/knowledge/project_frontend_diagnosis.py — projects the final class

into each failed project's reports/diagnosis.json + fix_log.jsonl and re-ingests, so knowledge carries synth-frontend- events and the exclude decision (negative learning)

• casebook/diagnosis/strategy refreshers (journal-side JSON)

4. Validate

• scripts/validate/check_mapped_netlist_duplicates.py (cross-corpus dedup)
• scripts/validate/audit_near_duplicates.py
• scripts/validate/validate_publish_readiness.py → quality/publish_validation.json

5. Publish

• scripts/report/score_design_quality.py + score_download_repos.py
• scripts/publish/build_publish_candidates.py → publish eligibility
• scripts/publish/refresh_expanded_raw_manifest.py → the merged

netlist-graph corpus manifest (only when the validation gate passes)

6. Snapshot

• scripts/publish/record_dataset_snapshot.py → runs/dataset_snapshot_latest.json

7. Promote (optional bridge to signoff-loop)

scripts/promote/promote_candidates.py |--all [--require-publish-eligible] [--platform P] [--run] — one-click conversion of a synth-proven candidate (index status==success) into a ready-to-run full-flow project under design_cases/: initproject skeleton, RTL vendored into /rtl/ (self-contained — the synth workspace is cleanable scratch), config.mk from signoff-loop's template carrying the proven knobs (VERILOGFILES/INCLUDEDIRS, ABCAREA, SYNTHMEMORYMAXBITS, SYNTHHDLFRONTEND, VERILOGTOPPARAMS) plus the floorplan directive (COREUTILIZATION, PLACEDENSITYLBADDON ≥ 0.10) and WITHOUT R2G_FLOW_SCOPE=synth_only (a promoted project ingests full-flow), constraint.sdc with a detected clock port (virtual-clock fallback), then validateconfig.py as the readiness gate. Verdict in /reports/promote.json + provenance in metadata.json; --run kicks run_orfs.sh immediately. Hand the promoted project to signoff-loop.

Running a full round

python3 scripts/run_expansion_round.py --discover --run-retry
# loops: scripts/run_until_empty.py, scripts/search_and_expand_until_target.py

Check workspace/runs/run_manifest_latest.json + quality/publish_validation.json; a round is fully successful only when publish gating and the manifest refresh completed as expected.

Hard Rules

• Never two concurrent candidates with the same DESIGNNAME + FLOWVARIANT.

The expand stage derives FLOW_VARIANT from the unique candidate id — keep candidate design values unique per round.

• Cap concurrency: R2G_ACQUIRE_NUM_CORES so flows × cores ≈ machine.
• Ingest after EVERY flow — pass or fail. A synth-fail run with no

failure_event in knowledge.sqlite is a loop bug (check with scripts/knowledge/project_frontend_diagnosis.py --check ).

• A SKIPped graph stage is not success — graph_skipped designs are not

publish-eligible; provision R2G_GRAPH_PYTHON and re-run.

• Do not treat synthesis success as publish success — publish gating +

the merged-manifest refresh define publish.

• Deterministic repair before LLM. The LLM patch path is default OFF

(R2G_ACQUIRE_ENABLE_LLM=1 to opt in; OpenAI fallback additionally needs OPENAI_API_KEY). Do not route template-placeholder failures to LLM when deterministic template_materialization applies.

• Never mutate the ORFS checkout or another skill's tree — this skill

writes only under its own roots + the knowledge DB via the ingest contract.

• v1 is nangate45-scoped; platform generalization is a separate effort.

Definition Of Success (keep these separate)

• execution success — ORFS synth + graph conversion succeeded (success

in index.csv, loadable netlist_graph.pt, cells > 0)

• repair success — a retry/deterministic fix made a failing design

runnable (closes its fix trajectory as cleared)

• validation success — dedup/quality/publish checks passed
• publish success — design appears in publish_eligible_designs AND the

merged manifest refresh included it

• learning success — the round's runs are in knowledge.sqlite

(flow_scope='synth_only'), synth-fails carry synth-frontend-* events

References

• task → script lookup + command templates: references/operation_matrix.md
• full script inventory: references/script_index.md
• candidate CSV schema: references/candidate_csv_schema.md
• failure KB + taxonomy: references/failure_knowledge_base.md,

references/failure_family_taxonomy.md

• policy files (candidate/repair/quality/publish/…): references/*.json
• ingestion plan + convergence decisions:

docs/superpowers/plans/rtl-acquire-ingestion-2026-07-09.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ShenShan123
• Source: ShenShan123/r2g-skills
• License: MIT

Install and usage instructions live in the source repository linked above.