Merge branch 'master' of https://github.com/The-OpenROAD-Project-private/OpenROAD into grt_fill_via

Author: eder-matheus

.claude/skills/triage-issue/SKILL.md .agents/skills/triage-issue/SKILL.md.claude/skills/triage-issue/SKILL.md renamed to .agents/skills/triage-issue/SKILL.md

@@ -0,0 +1 @@
+../.agents/skills

.claude/skills

@@ -0,0 +1,2 @@
+description = "Triage an OpenROAD GitHub issue by reproducing the bug and minimizing the test case with whittle.py. Use when an issue has an attached tarball artifact (.tar.gz) from `make *_issue`."
+prompt = "Activate the triage-issue skill and triage the following issue: {{args}}"

.gemini/commands/triage-issue.toml

@@ -0,0 +1,5 @@
+{
+  "context": {
+    "fileName": "AGENTS.md"
+  }
+}

.gemini/settings.json

@@ -0,0 +1,20 @@
+# OpenROAD - AI agent context
+
+This file provides project-specific guidance for AI agent sessions working on the OpenROAD codebase.
+
+## Quick Reference
+
+Detailed guides are in `docs/agents/` subdirectory:
+
+- **Build Pitfalls**: See `docs/agents/build.md`
+- **Testing Guide**: See `docs/agents/testing.md`
+- **Git & CI**: See `docs/agents/ci.md`
+- **Coding Patterns**: See `docs/agents/coding.md`
+
+## Critical Rules
+
+1. **Never modify `src/sta/` files** -- OpenSTA is managed upstream (`Sdc.cc`, `Power.cc`, `Sdc.tcl`, etc.). **Only test files may be modified.** All fixes must be in OpenROAD code (e.g., `src/dbSta/`, `src/rsz/`). If OpenSTA code change is inevitable, notify user. Exception: you *may* modify `src/sta/` files temporarily for **debugging purposes** only.
+2. Run `clang-format -i <files>` for C++ files before commit. **NEVER** for `src/sta/*` and `*.i` files.
+3. **Always use `git commit -s`** for DCO compliance.
+4. When amending submodule commits, parent repo submodule reference must also be updated via `git submodule update --init --recursive`. It is needed after any merge/pull.
+5. **Trace bugs upstream** -- when a bug appears in output (e.g., Verilog), find the data creation point (e.g., `buffer_ports`, `remove_buffers`), not the serialization point (e.g., `VerilogWriter`).

AGENTS.md

@@ -0,0 +1 @@
+AGENTS.md

CLAUDE.md

@@ -0,0 +1,12 @@
+# OpenROAD Build Pitfalls
+
+## Debug vs Release Build Behavior Differences
+
+When tests pass locally (Debug) but fail in CI (Release), check for:
+- **Uninitialized members**: Debug zero-initializes memory; Release leaves garbage
+- **nullptr through custom hashers**: e.g., `PinIdHash::operator()(nullptr)` segfaults in Release only
+- **Subnormal float values**: Uninitialized floats may be zero in Debug but subnormal in Release
+
+## Shared Library RPATH vs LD_LIBRARY_PATH
+
+External tool binaries (e.g., kepler-formal) have RPATH baked in pointing to the original install location. After rebuilding a dependency, you must either `cmake --install` to the RPATH location or use `LD_PRELOAD`/`patchelf`. Setting `LD_LIBRARY_PATH` alone may be insufficient if RPATH takes precedence.

docs/agents/build.md

@@ -0,0 +1,30 @@
+# CI Workflow
+
+## Pull Requests
+
+### Never Close/Reopen a PR to Retrigger CI
+Never close a public PR to retrigger CI -- `gh pr reopen` requires **admin permissions**. To retrigger CI, use empty commits instead:
+```bash
+git commit --allow-empty -s -m "retrigger CI"
+```
+
+### `gh pr checks` Exit Code 8
+Exit code 8 means some checks are still pending -- not an error.
+
+### Clang-Tidy CI
+Clang-Tidy CI can fail not only for code issues but also for **unresolved review comments** on the PR. Review threads cannot be resolved via API on public repos -- must be done on the GitHub web UI.
+
+## CI Artifacts
+
+- Use distinct filenames for public vs private artifacts (never overwrite one with the other)
+- Files >4GB may need `7z x` or `python3 -m zipfile -e` instead of `unzip`
+- When possible, download only specific `metadata.json` files instead of the full archive
+- Do not commit `metadata-base-ok.json` -- we have decided not to manage this file.
+
+## Private-to-Staging Sync
+
+To sync a private repo PR to the staging (public) repo:
+1. Push commits to the **private repo** (`The-OpenROAD-Project-private/OpenROAD`)
+2. Add the label **"Ready To Sync Public"** on the **private repo PR**
+
+**Important**: The label is **consumed** after each sync (removed by the sync bot). After pushing new commits, you must **re-add** the label. If the label already exists, remove it first, then re-add to trigger the workflow.

docs/agents/ci.md

@@ -0,0 +1,36 @@
+# OpenROAD Coding Patterns
+
+## Style Rules
+
+### General C++ Guidelines
+- Follow the Google C++ Style Guide.
+- Use modern C++20 style and features.
+- Apply `const` qualifiers whenever possible.
+
+### Type Declarations
+- Use C++ casts, not C-style casts
+
+### Braces
+- Use `{...}` even for single-line statements
+
+### Comments
+- Do not remove existing comments
+- Recommend adding a single line comment for each important code block
+- All comments must be in English
+
+### Function Length
+- Factor out into multiple functions if a function exceeds 100 lines
+  - Exception: Unit tests can have long functions
+
+### Null Safety
+- Avoid adding too defensive null checks if the object cannot be null
+
+## Common Coding Mistakes
+
+### OpenROAD Message ID Duplicate Checker
+`etc/find_messages.py` uses regex to match **literal numeric IDs** in `logger->xxx(MODULE, NNNN, ...)` calls. When duplicating a message across modules, use named constants to bypass the checker:
+```cpp
+constexpr int kMsgIdBufferInserted = 1234;
+logger_->info(RSZ, kMsgIdBufferInserted, "...");
+```
+

docs/agents/coding.md

@@ -0,0 +1,79 @@
+# OpenROAD Testing Guide
+
+OpenROAD has two types of tests: **integration tests** (Tcl) and **unit tests** (C++).
+
+## CAUTION -- Dual Registration Required
+
+**Every new test MUST be registered in BOTH build systems. Missing either one is a build break.**
+
+| Build System | Registration File | Block/Macro |
+|-------------|-------------------|-------------|
+| **CMake** | `src/<module>/test/CMakeLists.txt` | `or_integration_tests(...)` |
+| **Bazel** | `src/<module>/test/BUILD` | `regression_test(...)` |
+
+Forgetting the Bazel `BUILD` file is the most common mistake -- CMake-only registration
+silently passes local `make test` but the **test will be missing from Bazel CI**.
+
+## Integration Tests
+
+Integration tests are Tcl scripts located at `src/<module>/test` or `src/<module>/test/tcl`.
+
+### Running Integration Tests
+
+`./regression` is a ctest wrapper that filters by module label.
+
+```bash
+cd src/rsz/test
+./regression -R buffer_ports1   # run one test (regex match)
+./regression -R "repair.*hier"  # run tests matching pattern
+./regression -j4 -V             # all rsz tests, parallel, verbose
+
+# Or equivalently from the build directory:
+cd build
+ctest -R "rsz\.buffer_ports1\.tcl"
+```
+
+### Creating a New Integration Test
+
+Best practice reference: `src/rsz/test/repair_tie12_hier.tcl`
+
+1. **Header comment**: First line must explain the test purpose
+   ```tcl
+   # [Brief description of the test]
+   ```
+
+2. **Set test name**: Used for output file generation
+   ```tcl
+   set test_name <integration_test_name>
+   ```
+
+3. **Output naming with `make_result_file`**: Use for temporary output files
+   ```tcl
+   set verilog_filename "${test_name}.v"
+   set out_verilog [make_result_file $verilog_filename]
+   write_verilog $out_verilog
+   ```
+
+4. **Verification with `diff_file`**: Compare against golden files
+   ```tcl
+   diff_file ${test_name}.vok $out_verilog
+   ```
+
+5. **Generate `<test_name>.ok` file**: Create golden test log by executing the script, redirecting stdout, and removing the openroad banner at the top.
+
+6. **Registration (BOTH files for CMake and Bazel -- do NOT skip Bazel)**
+
+### Test Framework Flags
+- `-no_splash -no_init -exit`
+
+### Golden File Notes
+- `.ok` = log golden file (full stdout), `.vok` = verilog golden file
+- **`diff_file` reports only the first difference** -- when regenerating golden files, regenerate the entire output file rather than relying on incremental diffs.
+
+## Unit Tests
+
+Unit tests are C++ files located at `src/<module>/test/cpp`.
+
+### Test Registration
+- CMake: `src/<module>/test/CMakeLists.txt`
+- Bazel: `src/<module>/test/BUILD` or `src/<module>/test/cpp/BUILD`