# Spec To Rtl

> MANDATORY entry point when `design_one_shot_runner.step_rtl_gen` WAIVES with `fallback_skill='spec-to-rtl'`. This is invoked for every IC class with `rtl_gen=null` in `ic_class_registry.json`, which is the SOURCE OF TRUTH for that set and the thing the runner actually routes from -- at the time of writing the 11 such classes are bare_fpga, bus_interconnect_protocol, bus_peripheral, crypto_accelerator, data_converter, digital_arithmetic_primitive, digital_cmd_driven, processor_cpu, pure_analog, serial_peripheral_protocol, unknown_protocol_class. The runner has already (1) ingested the prompt into L1-L27, (2) detected the IC class, (3) set the expected RTL path. This skill authors synthesizable RTL into the runner's expected path so the runner's downstream gates (chip_top auto-emit, rtl_hygiene_lint --fix, eda_lint, eda_synth, rtl_repair_retry, spec_conformance_check, full_stack_tb_gen) can fire on it. Triggered automatically by the runner's WAIVE message; also fires on phrases like 'AI invokes spec-to-rtl', 'r

- Skill: `vibeic/spec-to-rtl` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add vibeic/spec-to-rtl`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vibeic/spec-to-rtl/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: vibeic (https://skillmd.com/u/vibeic)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/vibeic/spec-to-rtl

---


# spec-to-rtl — the runner-orchestrated AI authoring step

## Register value convention

Read `flow/rtl_conventions.json#register_initial_value` from this plugin tree
before writing, repairing or reviewing RTL. A value stated in the original input
wins. If the input is silent, use a recognized circuit-class convention from
the table when one applies; otherwise use zero, including internal state. Use a
reset assignment when the register has a reset, otherwise an `initial` assignment. A reset is the startup mechanism unless the input explicitly requires a
separate initial value. Mark defaults and conventions visibly in RTL comments and list
register, value, mechanism and convention/source in the report. On chip and IP routes, initial-only
storage is a reported, nonblocking finding. This table defines the input/convention/zero
precedence. Never derive values from a testbench, scorer, reference
answer or score. The scorer must not modify candidates.

## What this skill IS

The deterministic authoring path for IC classes WITHOUT a registered `rtl_gen`
generator. Spec → RTL fundamentally requires a language model (open-benchmark-
methodology skill § 1); this skill is **how the runner delegates that step to
the AI inside its own pipeline**, so the surrounding gates still fire.

## Invocation contract

### Skill: Functional RTL before production scan insertion

When the design declares production scan in L20, complete the functional RTL
authoring handoff before the native DFT steps. If the deterministic producers
decline, invoke this skill and write the functional RTL at the requested path.
The staged fallback is an authoring request; rerunning an empty RTL directory
does not complete it. Record AI authorship in the existing
`phase2/stage1/ai_backup_author.json` and reenter the normal public runner.

Preserve the functional interface, reset behavior and timing from the design
input. Native DFT insertion owns scan-cell replacement, stitching and the added
test ports specified by L20. Determine chain length from the implemented design.
Review the native scan replay and subsequent functional replay separately.
Functional simulation alone does not establish scan or ATPG acceptance.

For an existing AI_BACKUP task carrying `spec_clarification`, read the complete
original input and its two source-bound observable readings. Choose one
source-compatible reading for each request and actually author the RTL in
`write_rtl_to`. Record `selected_readings` as one integer 0 or 1 per request,
with source quotes, rationale and the named AI author in the normal completion
record. Do not relabel preserved Program RTL as AI work. Fresh authoring may
produce identical bytes. The coordinator preserves the original Program result,
candidate, review and tests; it retires only its mutable RTL workcopy. Reenter
the existing native gates and fresh independent review before acceptance. The
choice does not waive failed challenges, rewrite source, or earn Program credit.
Do not requeue the same ambiguity after that choice has been completed.

When `design_one_shot_runner.step_rtl_gen` WAIVES with the message:

> *IC class 'XXX' registered but rtl_gen=null. Recommended action: AI invokes
> skill `spec-to-rtl`.*

…the AI MUST:

1. **Read the input contract named by the runner handoff**. For the explicit
   bounded D09 position 17 `input_authority=original` contract, read the **entire**
   `read_prompt_from` file and every `read_context_from` file. Verify their
   recorded SHA-256 values before authoring or reviewing. These are the
   authoritative source bytes; do not substitute generated Ldocs or require a
   D01 position 1 document review for this RTL-only request. A changed or missing source
   requires returning to the ordinary runner, not silently adopting it. This
   handoff asserts neither D01 position 1 PASS nor measured RTL behavior.

   For the default structured contract, **read the L docs the runner emitted**:
   - `<project>/phase1/generated_docs/L1_*.json` (product metadata, IC name, target clock)
   - `<project>/phase1/generated_docs/L2_*.json` (functional spec)
   - `<project>/phase1/generated_docs/L3_*.json` (external interface — ports)
   - `<project>/phase1/generated_docs/L7_*.json` (verification plan / truth-tables)
   - `<project>/phase1/generated_docs/L9_*.json` (constraints, top_module name, top_ports)
   - For Path-A (NL prompt) projects, ALSO read the original prompt at
     `<project>/input/phase1_prompt.md` or `<project>/input/docs/*.md`. The
     prompt typically has clearer port-name and behavioral details than the
     auto-extracted L docs.
   - When the handoff supplies verified `public_original_input_paths`, ALSO
     read those original RTL and context files. Preserve their exact interface
     and supplied behavior while applying the prompt's requested completion
     or change; use the same authoring method below with these source inputs.

   **— and CONSULT THE CAPTURED-LESSON DIGEST (MANDATORY) —**
   The runner's WAIVE step deterministically writes
   `<project>/phase2/stage1/lessons.md` (and sets `lessons_digest` +
   `lessons_count` in its handoff `extras`): a chip-AGNOSTIC digest of every
   `### Skill:` genre/topology convention captured from prior recoveries.
   BEFORE you author, OPEN it, keyword-match THIS design's genre against each
   section's `**When to apply**` line, and APPLY every match. These are general
   advisory patterns (frequency/clock-divider dual-edge-OR LEVEL topology,
   shifter logical-vs-rotate default, FIFO Gray-pointer, restoring-divider
   remainder width, overlapping-sequence FSM re-seed, valid/ready handshake
   inference, …), **not per-problem answers**. Use a matched technique only when it is
   consistent with the complete current input. Record choices the source leaves
   free; a prior checker or benchmark result cannot supply missing intent.

   **— and LIST THE OTHER ARTIFACTS THE SPEC MAKES MANDATORY (MANDATORY) —**
   The WAIVE handoff tells you two things: write the RTL here, and read
   `lessons.md`. It says nothing about the OTHER artifacts the same spec makes
   mandatory and that you are the only one who can produce. Those clauses are
   already extractable from the SAME input docs you have just read, so run the
   preflight BEFORE you author:

   ```bash
   python3 plugins/vibe-ic/programs/spec_required_artifact_check.py \
       <project> --preflight
   ```

   It prints every still-OUTSTANDING spec-declared artifact with the input doc
   and the clause that demands it, and **always exits 0** — at handoff those
   files are legitimately absent, so it can never block a correct run. Author
   each one alongside the RTL. Skipping this does not make the requirement go
   away: the same extraction runs as a BLOCKING assertion at `final_audit`, so
   a missing declaration costs an entire Phase 2 (hygiene, lint, synth, DFT, a
   multi-minute LEC) to discover a file that took seconds to write.

   **— and DECIDE + RECORD YOUR FREE CHOICES *BEFORE* YOU AUTHOR (MANDATORY) —**
   The preflight above tells you WHICH files the spec demands. When one of them
   is a DECLARATION — a "MUST declare `<path>`" clause followed by a field table
   — the file is not paperwork you can write afterwards. Its fields are FREE
   CHOICES: decisions no downstream tool can recover by inference (serial bit
   order, reset-release latency, integer encoding, reset polarity, the parameter
   this build ran at, which optional feature axis you selected). Two correct
   designs disagree on all of them, so the comparison procedure cannot pair its
   reference output unless you tell it.

   The runner already staged the contract for you at
   `<project>/phase2/stage1/declaration_contract.json` (extras key
   `declaration_contract`). Read it, DECIDE each field, and record them:

   ```bash
   python3 plugins/vibe-ic/programs/spec_declaration_emit.py <project> --contract
   python3 plugins/vibe-ic/programs/spec_declaration_emit.py <project> \
       --set <field>=<value> --set <field>=<value> ...
   ```

   Then author RTL that CONFORMS to what you declared — not the other way round.

   Rules that are easy to get wrong:
   - The emitter **refuses** (rc=1, naming the field) while any REQUIRED choice
     is undetermined, and writes nothing. That refusal is correct: a
     default-filled declaration would turn the required-artifact gate green
     against a value nobody chose.
   - **Do not copy the spec's example value** into the declaration. The example
     column records what a reference implementation happened to pick; copying it
     makes the document author the designer.
   - An informational field you did not decide is **omitted**, never
     placeholder-filled.
   - `--from-rtl-declaration` exists ONLY for a legacy design whose RTL was
     written before the declaration; it promotes an existing
     `key = value` header block and stamps every field it takes as
     `recovered_from_prose` in the provenance sidecar. Do not use it as the
     normal path — a free choice recorded only in an RTL comment is a free
     choice a downstream tool has to guess.
2. **Respect the blind rule**: read ONLY the L docs, original prompt, and the
   handoff's verified `public_original_input_paths` when supplied. NEVER read
   hidden or unlisted benchmark testbenches, harnesses, or reference RTL (for
   example `testbench.v` or `verified_*.v`). This is enforced by the open-benchmark-
   methodology skill's absolute-blindness rule and applies inside this skill.
3. **Determine the module name**:
   - If `L9_INTEGRATION_SPEC.json` declares `top_module` (e.g. `"chip_top"`)
     AND that matches the description's stated module name, use that.
   - Otherwise: use the **exact name the
     prompt/description states** ("Module name: <name>") as its supplied
     interface contract. The runner's chip_top auto-emit (v0.1.32+)
     will wrap your module if L9.top_module differs.
4. **Author synthesizable RTL** at the runner's expected path:
   ```
   <project>/phase2/stage1/rtl/<module_name>.v   (or .sv)
   ```
   - Verilog-2001 or SystemVerilog; synthesizable for yosys + gf180/sky130
   - EXACT port list per L3 / L9: names, directions, widths (`[3:0]` ⇒ 4 bits)
   - Implement the behavior the description states. Algorithm choices the
     description doesn't pin down are R3-permitted design freedom.
5. **Apply known hygiene proactively** (so the runner's gates don't have to
   work around them):
   - Combinational `always @(*)` blocks: every branch assigns every output
     OR a `default` covers them (no inferred latches).
   - Reset-less registered outputs: when input is silent or ambiguous, add
     `initial <reg> = 0;` in a SEPARATE `initial` block (not inline on an output
     declaration), matching `rtl_hygiene_lint --fix`, and record this DEFAULT as
     an assumption. Only an explicit contrary initial value overrides it; preserve
     a supplied nonzero startup value rather than resetting it to zero.
   - `case`: include `default`; rewrite overlapping `casez` priority encoders
     as `if/else-if`.
6. **Run native validation before handoff.** Compile the RTL with the actual
   selected top, source set, include paths, defines and parameters. Use full
   native simulator code generation and native lint. Run a functional testbench
   derived only from the prompt's worked examples, tables, boundaries and error
   behavior. Missing execution remains NOT_MEASURED. Preserve benchmark actor
   isolation; the author does not read the hidden harness or oracle.

6b. **Prompt→interface conformance pre-emit check (ORGANIC #695)**. Before
   handing back, run the deterministic interface gate — it reads ONLY the
   prompt + your RTL (BLIND; never the oracle/hidden TB) and flags the three
   PROMPT-DERIVABLE interface misses that prevent a supplied caller from binding:

   ```bash
   python3 plugins/vibe-ic/programs/iface_conformance_v2.py \
       --id <problem_id> \
       --prompt <prompt.txt> \
       --rtl <project>/phase2/stage1/rtl/<module_name>.v
   ```

   It checks (1) MODULE-NAME-CASE — the RTL module name must match the
   supplied interface header CASE-EXACTLY (`stream_unit` and `StreamUnit`
   are different names). If the input leaves the name open, use the supplied
   file/id stem DEFAULT and record the assumption; only explicit contrary input
   overrides it. The interface header wins; check any public instantiation
   supplied as input for consistency; (2) MISSING-PORT — every
   interface signal the prompt NAMES (table rows, backtick signal names with a
   nearby direction, a given-code module header, wavedrom `name` entries) must
   appear in your port list (AXI master must keep `ar*`/`aw*`, `s_ready`, etc.);
   (3) PORT-DIRECTION — a port's direction must match the prompt's signal table
   (do not declare an output where the supplied interface declares an input).
   ADVISORY by default (prompt extraction is heuristic — an internal signal
   mentioned in prose is NOT a port and must not block); add `--strict` to make
   any finding exit 1 once you've confirmed the named signals really are ports.
   FIX every confirmed finding before emit — these are deterministic
   elaboration/bind failures implied by the supplied interface.
6c. **Spec-first coverage attribution pre-emit gate (ORGANIC #697)**.
   Enumerate requirements from the complete supplied input chain and exercise
   them with independent tests. This local coverage check cannot predict the
   coverage or expected behavior of held-back tests. It reads only supplied
   inputs, generated L-docs, candidate RTL and the current self-testbench.

   ```bash
   python3 plugins/vibe-ic/programs/spec_coverage_check.py \
       --prompt <prompt.txt> --ldocs <project>/generated_docs/ \
       [--fact-graph <fact_graph.json>] \
       --rtl <project>/phase2/stage1/rtl/<module_name>.v \
       --tb  <your_functional_tb.sv> --strict
   ```

   It extracts a DETERMINISTIC checklist (ports/widths/directions, reset
   value+polarity+sync/async, stated latency, every table row, every worked
   example, **every ENUMERATED SET + its outside-the-set/default boundary** —
   the most-missed #697 pattern — signed-ness, byte order, overflow, handshake)
   from EVERY chain station and reports any item your TB leaves UNCOVERED
   (`--strict` BLOCKs on a coverage gap). FIX the gap by adding the missing
   directed stimulus/assertion (especially an OUTSIDE-the-set value for any
   enumerated set). On a downstream FAIL, re-run with `--failure "<behavior>"`:
   a `coverage-gap` ⇒ enhance your TB; an `extraction-gap` ⇒ the program names
   the `route_to:` station (ic-expert-agent / spec-to-rtl) that
   dropped the requirement (community-backlog it); only a cited `spec-absent` is
   a genuine floor. The structural extraction + routing is deterministic;
   deciding whether a prose sentence is a distinct *testable* requirement (so
   you can author its stimulus) is your LLM judgment.
7. Return the authored RTL and handoff to the public
   `vibe_ic_one_shot_runner.py` entry using the original project, route, and
   Router-selected evidence window. The native runner executes the applicable
   validation, CDC, simulation, and formal tools. Read each native result
   against its original limit. Missing measurements remain `NOT_MEASURED`, and
   tool failures remain `FAIL`. Authoring alone does not establish downstream
   or whole-chip acceptance. For benchmarks, independent blind AI review and
   official scoring remain required.

## What this skill IS NOT

- **NOT a fully-deterministic program**. Spec→Verilog needs an LLM; this
  skill is *the AI's role inside the runner pipeline*, with all the
  structural gates wrapping it.
- **NOT a bypass of the runner**. Bypass = authoring with MCP outside the
  runner's pipeline (no phase1 L doc context, no chip_top auto-emit, no
  hygiene `--fix`, no rtl_repair_retry, no conformance, no audit). Use this skill for the runner-issued authoring handoff.
- **NOT a free pass to ignore the blind rule**. The original benchmark's
  testbench / golden RTL are STILL HIDDEN during this authoring step. Only
  the host scorer (after all gates run) touches them.

## Quality bar

A "good" spec-to-rtl emission means:
- Read the native simulation or formal result for the selected source, top and configuration. Do not add a separate harness-identity or source-hash requirement.
- `eda_synth` gf180 emits ≥1 cell (not pure-passthrough; not optimised to nothing).
- The module name + port list match the description verbatim.
- No latches inferred (or, if a latch IS intended per the description,
  declared `always_latch`).
- Reset-less registered outputs use a separate initial-zero block by DEFAULT
  when input is silent or ambiguous; record the assumption. An explicit contrary
  startup value overrides this default and is preserved.

If you cannot satisfy this from the description blindly (e.g. the description
genuinely under-specifies a parameter the TB will instantiate by name), emit
your best honest reading and let the runner's downstream gates report the
mismatch. Per the open-benchmark-methodology skill § 4 Cat B, that's
documented as benchmark under-specification, not a skill failure.

## Runner handoff

The runner-issued authoring handoff names this skill and the required output path.
Use that handoff to continue inside the normal product flow. An absent skill or
input is a product handoff defect, not a benchmark answer or a design verdict.

## Error-flag behavior — classify recoverable vs fatal from L3/L5 (#468)

When you author RTL that raises an error flag on an undefined-access /
illegal-command / out-of-range path, decide from the **L3/L5 protocol prose**
(not from convenience) whether the FSM should **recover** or **halt**, and encode
that decision in RTL behavior and document it for `/rtl-review`:

- **recoverable** — if L3 (transaction protocol) / L5 (error-handling spec) says the
  block sets the error flag and **continues serving the next transaction** (returns to
  IDLE/ready), implement exactly that: raise the flag, then transition back to the
  serving state. Add a `// fsm_error: recoverable` annotation at the error-assign site
  so the reviewer can confirm without re-deriving the semantics.
- **fatal** — if L3/L5 binds the error to a **halt/lockup state** or says it
  **requires a reset (or explicit clear) to clear**, implement the halt and do NOT add
  the recoverable annotation; the FSM stays in the error state until reset.

**FORBIDDEN:** annotating a site `// fsm_error: recoverable` (or, in review, dismissing
a behavioral failure) **without** the L3/L5 sentence(s) that establish the halt-vs-continue
behavior. The annotation is a claim about the spec and must be backed by spec text.

Verify the decision with a prompt-derived executable challenge: trigger the
error, offer the next legal transaction and check either the specified recovery
or the required halt until reset/clear. Read the native simulation or formal
result against the unchanged requirement and AI review it. Missing evidence is
`NOT_MEASURED`. A hygiene lint result does not prove error recovery or fatality.

**why_not_bucket_a:** the recoverable-vs-fatal call is a semantic judgment
that lives in protocol prose (L3/L5), not in RTL structure; the identical
`error <= 1'b1` line means "keep going" in one protocol and "lock until reset" in
another, so no deterministic rule over the RTL can decide it. This is the residual LLM
authoring judgment, cross-referenced with `/rtl-review`'s matching classification
section.

## Output timing — same-cycle (Moore-combinational) vs registered pulse (#560)

For an INPUT-defined same-cycle status / event / strobe, a **registered** pulse
(`out <= <event>;` under a clock) can add a cycle that violates that requirement.
A self-authored cocotb check must use the source-defined observation phase;
a testbench's own sampling style cannot decide the required output timing.

**Decide the output's timing from the complete supplied INPUT, then encode it:**
Read prose, diagrams and timing tables together. The forms below are techniques,
not a universal keyword rule. If timing remains silent or ambiguous, send it to
AI authoring with that ambiguity named.

- **same-cycle (Moore-combinational decode)** — when the spec describes the
  output and its triggering event in the **same breath** ("asserts `done` *when*
  the count reaches N", "drives `error` *on* an invalid command", "`valid` is
  high *while* in state S") and the complete INPUT fixes that same-cycle
  relation, derive the output **combinationally from state / inputs** and do NOT register it:

  ```verilog
  // Moore decode — same-cycle, no register delay
  assign done = (state == DONE);
  always @(*) error = (cmd_valid && !cmd_legal);
  ```

  This serves source-defined state decodes and same-cycle event strobes;
  an unprovided checker cannot make it the default for an ambiguous interface.

- **registered / next-cycle** — ONLY when the prose explicitly says the output
  is **registered**, appears **one cycle after** the event, is **pipelined**, or
  must be **glitch-free** for an external interface. Then use the NBA form:

  ```verilog
  always @(posedge clk) out <= <event>;   // intentional 1-cycle latency
  ```

**Application examples:** an input-defined same-cycle vending-machine
`error`+`return`, an output required to track an FSM state, or a source-defined
same-cycle serial-interface event can use a combinational decode. Verify the
specified phase with an input-derived check; previous benchmark FAIL/PASS
outcomes do not establish which phase a new design requires.

**why_not_bucket_a:** same-cycle vs registered is a reading of the spec prose
("when"/"on"/"while" vs "registered"/"one cycle later"/"pipelined") together
with its supplied diagrams and edge relations, not a hidden testbench convention. The identical event→output mapping is correct
as combinational in one problem and as registered in another; no regex over the
RTL or the prompt reliably separates the two, so this stays an LLM authoring
judgment.

## Independent differential self-verification

When the RTL and its testbench share one interpretation, both can repeat the
same semantic mistake. Derive an independent reference from the actual input,
including clock-edge timing, reset values, latency, signedness, bit order,
overflow and default/error behavior. Preserve benchmark blindness.

Drive the RTL and reference with the same directed, random and boundary
stimuli using the selected native simulator. Compare every required output at
the source-defined sampling event. Retain the first mismatching cycle, signal
and input sequence. Read the source to decide which implementation is wrong,
then add that input-derived case to the regression and rerun. Agreement on a
bounded test set does not establish complete correctness.

## Latency/timing conformance — the PROGRAM measures, not your self-TB (#705)

When the spec states an **EXACT** latency — "output asserts **N cycles** after
the start event", "**WIDTH+2**-cycle delay", "**1 cycle overhead** when
transitioning IDLE→BUSY registering inputs" — **DO NOT trust your self-TB's
measurement.** An expected model derived from the same mistaken edge convention
can confirm incorrect RTL. Derive the event, counting edge and observation point
independently from the current supplied timing contract.

`latency_conformance_check.py` measures the selected event and output. Its
one-clock active-high event pulse and positive-edge count are an explicit
measurement convention, not a universal interface contract. Use this mode only
when it implements the supplied event polarity, duration, counting edge and
observation point. If that contract differs, adapt the measurement stimulus to
the input or report the unsupported measurement. Never change RTL to match an
inapplicable measurement convention. A mismatch calls for RTL repair only after
confirming that the measurement implements the input contract.

```bash
python3 plugins/vibe-ic/programs/latency_conformance_check.py \
    --rtl <your_rtl.sv> --top <module> \
    --event <start_port> --output <valid_port> --expect "<expr>"
```

- `--expect` is the spec latency literal as arithmetic over the module's
  parameters (`WIDTH+2`, `N+1`, `8`); resolved against the `#(...)` defaults (or
  a `--param NAME=VAL` override). It is evaluated by a tiny SAFE evaluator
  (digits, param names, `+ - * // ( )` only — never `eval`).
- `LATENCY-MISMATCH: measured=<m> but spec <expr>=<e>` (rc 1) = your RTL's real
  latency under this measurement is `<m>`. Confirm its event and edge convention
  against the input before repairing RTL or correcting the measurement.
- `latency-conformance ok: measured=<m> == spec <expr>` (rc 0) = the measured
  latency matches the spec literal — emit.
- iverilog absent → a distinct `SKIP` (rc 0), **never** a fabricated PASS; the
  output never asserting → `LATENCY-TIMEOUT` (rc 1).

**why_not_bucket_a:** the canonical MEASUREMENT (build the TB, pulse the event,
count posedges to the output assertion) + the comparison against the resolved
literal IS the deterministic program. The LLM residual is reading the spec to
decide **WHICH** port is the event, **WHICH** is the output, and **WHICH**
expected expression the prose names (`WIDTH+2` vs `N+1` vs a constant). This is
the timing complement to **#697** (coverage attribution — force the self-TB to
COVER each dimension) and **#700** (independent differential verify — cross-check
a second derivation): #705 supplies the absolute latency yard-stick those two do
not.

## "Read the simulation waveform" tables — the PROGRAM replays the published table (#716)

When the prompt embeds a **literal simulation table** — rows of
`time [clk] <input...> [internal...] <output>` under a "**Read the simulation
waveforms to determine what the circuit does, then implement it**" instruction
— the table **IS** a directed test vector you
must reproduce **exactly**. Count pipeline depth from the **first DEFINED output
transition**, not from the first `x`. Early X rows are not an extra register stage:
an input-sampling NBA race (`@(posedge) a<=val`) can leave the input unknown at the
first edge, and the table's X-match convention consumes that unconstrained window.
Do NOT add a stage just to explain early X. Keep this default on silent or ambiguous
stage-count wording and record the assumption; an explicit contrary latency or
fully defined timing requirement overrides it. Check every defined row. For a real
source conflict, pick by declared precedence, record it, and emit RTL without asking
a human or importing a hidden reference's implementation.

`waveform_table_conformance_check.py` is the independent yard-stick. It parses the
table and replays it with its implemented X-match (X in the table matches
anything; X in the DUT only matches a table X). Confirm that this comparison
convention matches INPUT; a scorer cannot supply missing X semantics. It
**BLOCKS on any mismatch** under that convention:

```bash
python3 plugins/vibe-ic/programs/waveform_table_conformance_check.py \
    --prompt <prompt.txt> --rtl <your_rtl.sv> --top <module>
```

- `WTC_PASS` (rc 0) — the RTL reproduces the published table; emit.
- `WTC_FAIL mismatches=<n>` + per-row `WTC_MISMATCH t=.. expected=.. got=..`
  (rc 1) — your RTL diverges from the table (the stage-count / inversion /
  function is wrong). Fix and re-run.
- `WTC_SKIP_<reason>` / `WTC_NO_TABLE` (rc 0) — the prompt has no table, OR the
  design is **outside the proven-faithful envelope** (a negedge / level-sensitive
  **transparent latch**, a **multi-bit/hex** output column, a Moore FSM exposing
  **multiple observable outputs**, or non-binary table values). The gate
  **refuses to block** these — its replay timing is only proven faithful for
  combinational truth-tables and single-bit single-clock **posedge-registered**
  outputs, so for everything else it advises rather than blocks (NO false-block).
- iverilog absent → `WTC_SKIP_no_tools` (rc 0), never a fabricated PASS.

**why_not_bucket_a:** parsing the table, building the directed replay TB, running
it under its documented X-match, and comparing every row IS the deterministic
program. The LLM residual is reading the prose to confirm it is a
"read-the-waveform" problem and, on a `WTC_FAIL`, deciding WHICH clause of the
RTL (stage count, polarity, function) the mismatch implicates. This is the
DIRECTED-VECTOR complement to **#700** (a random differential cross-check, which
is circular here because a stage-count misread biases BOTH the RTL and a
hand-derived `ref`) and **#705** (which needs a prose latency literal a
waveform-only prompt does not supply).

## Behavioral-prose Moore FSM — extract the table, let the PROGRAM emit (2026-06-23)

Most FSMs whose states + transitions are stated in NARRATIVE PROSE (Lemmings with
dig/splat/counter precedence; a PS/2 byte-boundary search; a sliding-window counter;
a multi-phase controller) still need a language model to read prose into structure.
One strict basic carve-out is already program-solved: when a directional bump+fall
walker explicitly states both direction mappings, both-side behavior, fall/resume
memory, all three bump/fall boundary priorities, Moore outputs, reset, and clock
edge, `behavioral_fsm_synth.py` parses those facts into a complete four-state table
and the registry emits it. Missing any fact or adding dig/splat/timer behavior is a
safe SKIP. For every remaining narrative shape, once the AI extracts a COMPLETE
enumerated table, emitting correct RTL is a pure formula. So DO NOT hand-author the
always-blocks — split the work:

1. **You (AI) extract the COMPLETE canonical Moore-FSM table from the prose** — every
   state, every Moore output per state, the reset (state + sync/async + level), and
   EVERY transition (one row per state × every input combination; UNROLL a counter
   like "falls for >20 cycles" into explicit states — the internal encoding is FREE
   because the TB observes only the Moore outputs). Inputs may be a 1-bit port or a
   bus bit-select (`in[3]`). The format is the docstring of
   `programs/moore_fsm_table_emit.py`.
2. **The PROGRAM emits + gates**: `python3 programs/moore_fsm_table_emit.py --prompt
   <prompt> --table <your.tbl> --top <TopModule>`. It VALIDATES the table is complete
   and matches the declared interface (rejects a hallucinated port, a missing input
   combo, an unknown next-state, a missing output) and emits the RTL, or SKIPs
   (exit 1). The emitted RTL is then your authored sample.

This is the §4.2 **AI-step-gated-by-program** pattern, not free-text authoring: the
program guarantees the RTL is a pure function of a table it proved complete, so a
mis-extraction becomes a SKIP, never a wrong-but-plausible machine. Proven
0-mismatch on the full Lemmings family (1–4, incl. the 47-state >20-cycle splatter
counter), PS/2 (`in[3]`), the 3-cycle window counter, and the multi-phase motor
controller. If your first table mismatches its self-TB, RE-READ THE PROMPT (never
the hidden reference) to fix the offending transition/output.

## Target-conditional variant recommendations — pick by the DECLARED target, or say why not (#2089)

A design input that ships several implementation variants of one block behind a
compile-time parameter usually also says WHICH ONE to pick, and makes that
conditional on the implementation target:

> "When disabling masking, it is recommended to use the unmasked Canright or LUT
> S-Box implementation for ASIC or FPGA targets, respectively."

MEASURED (#2089 F21): the authored variant was the FPGA one for a design whose
declared target is an open ASIC PDK. Nothing was wrong with the reading of the
RTL — the recommendation had never left the document, so there was nothing to
read it against.

**The deterministic half is already done for you.** Phase 1 extracts every such
sentence into `L8_RTL_CONSTANTS.target_conditional_recommendations[]`, one row
per target, each carrying `target`, `recommends`, the whole `sentence` and its
`source`. "A or B for X or Y, respectively" is distributed (`distributive:
true`); a sentence that DENIES a recommendation ("this is NOT recommended") is
dropped before it reaches you. Do NOT re-read the prose for this — read the rows.

**One case is already program-decided — do not re-decide it.** Where the
variant is selected by a compile-time parameter whose losing variants the cell
EXCLUDES from staging, the chip_top emitter now derives the value itself: it
narrows to the variants that are staged and consistent with what the input
declared, and among those it takes the one the recommendation names for the
declared target, recording `tie_break: "the design input's target-conditional
recommendation"` with the sentence in `rtl/.<top>__param_resolution.json`.

READ THAT SIDECAR BEFORE AUTHORING, AND READ ITS `tie_break`. It says which of
three things happened, and they are not the same answer:

  * `the design input's target-conditional recommendation` — the wrapper
    carries the variant the input recommends. Re-deciding it in the RTL you
    author is how the two disagree; don't.
  * `consuming module's own declared default` — the recommendation decided
    NOTHING here (no declared target, no row for it, no word that separates the
    survivors, or more than one survivor matched) and the value is a FALLBACK.
    The judgement is yours again: check it against the rows yourself and say so
    if you disagree with it.
  * a `refusals` entry instead of a `resolved` one — nothing was chosen and the
    step will FAIL by name. Declare the parameter; never weaken the check.

**What is yours, and why the rest cannot be a program.** Everywhere else,
pairing a row with THIS design needs the target and the prose together: the
declared target comes from L1's tapeout target / L9 / the PDK the run is pointed
at, and the recommendation names a variant in the document's own words, not in
the RTL's parameter vocabulary. So:

1. Read the declared target for this run. An open ASIC PDK is an `ASIC` target;
   a bitstream flow is `FPGA`.
2. If a row's `target` matches it, author THAT variant and cite the row's
   `sentence` in your handoff. Two rows for the same target that disagree is a
   finding to report, not a coin to flip.
3. If you author something else — the recommended variant is not staged, the
   design input contradicts itself, the parameter has no such value — SAY SO in
   one line, naming the row you did not follow. Silently authoring the other
   variant is the defect this section exists to close.
4. If no row matches the declared target, author nothing on this basis and say
   the input made no recommendation for it. An unconditional recommendation is
   NOT a row here on purpose.

**This pairs with the coupling refusal.** The same input that recommends a
variant usually also says that setting one parameter obliges another, and the
chip_top emitter REFUSES when the first is satisfied and the second is met by
NOTHING — neither stated by the input nor derived by the resolver above
(`COUPLED_PARAMETER_NOT_STATED`; the record's `satisfied_parameters` names the
set it judged). A DERIVED value satisfies the obligation, so you will not see
this refusal on a design whose variant the resolver could work out. When you do
meet it, the fix is to DECLARE the coupled parameter — with the value this
section's rows recommend for the declared target — never to weaken the check.

## Guard every declared legal parameter range at elaboration

Before authoring a parameterized module, read every explicit legal range in
the design input. If it says `WIDTH >= 5`, emit an elaboration guard such as
`generate if (WIDTH < 5) begin initial $fatal(1, "WIDTH too small"); end
endgenerate`. Check the declared default lies inside the range. A parameter
without a stated range needs no invented limit. The deterministic
`spec_conformance_check.py` reports a missing guard at the Phase-2 handoff.

### Skill: Reuse a stable accumulation baseline at the completion edge

When the input requires an iterative computation to keep its previous result readable
while busy, separate that observable result from the working state. If a new command
selects a constant initialization baseline, and a continuation command selects the
unchanged previous result, an extra register bank holding that baseline may duplicate
information already available at completion.

Latch the accepted command's baseline selector. Keep the previous result unchanged
while busy, then accumulate the stable working state into the selected constant or
previous result on the original completion edge. A separate pending-result bank is
also unnecessary when no consumer observes it and the working state remains stable
until that edge. Retain storage when the input or internal consumers need a snapshot
that would otherwise be lost; this is a scheduling choice, not a blanket register
removal rule.

Preserve reset aborts, command acceptance, mode latching, chained transactions and the
entire external READY/VALID/data timeline. Check those behaviors with native simulation
or formal tools, and remeasure mapped area at the same synthesis settings. Moving the
final addition can change timing, so synthesis area alone does not establish routed
timing, power or physical acceptance.

### Skill: Store the index used by critical selection logic

When a native worst path starts at an iteration counter and traverses an index
adjustment before a ROM, mux or operand array, store active counts in that
consumer's index domain. Reserve other encodings for idle and completion instead
of putting increment/decrement and range decoding before a high-fanout selector.
Reuse existing state bits when possible. Preserve command acceptance, reset
aborts, completion edges and the entire externally visible latency. Compare those
external behaviors and remeasure the original signoff corners; a new state
encoding alone does not prove timing closure.

## The sign-off corner is the SLOW corner, and a chain of adds is what misses it (#2081)

### Route an architectural timing failure

Read the selected native STA reports, constraints, corners and the path's
cell/interconnect breakdown. If physical repair cannot meet the original
period, explain why the limiting logic depth requires an architecture or RTL
change. A wrapper's silence does not prove that the architecture is adequate.
Keep the signoff corner and original period, and verify the proposed change
through native functional/equivalence and timing tools.

A single-cycle datapath authored so that it "looks like the algorithm" reads as
correct and closes at the typical corner. The corner the design input declares
for sign-off is the SLOW one, and there the SAME netlist misses — not by a
margin a resizer can find, but by the delay of carry chains you put in series
without deciding to.

The shape to look for: a register-to-register path that computes a sum of THREE
OR MORE operands, or that feeds one sum into another, at the datapath's full
word width. Written the way an algorithm specification writes it, each `+` maps
to its own ripple carry and the path traverses them end to end. A full-width
ripple carry can be a large fraction of a whole clock period at a slow corner,
so two in series is a miss that no amount of buffering recovers. It will not
show up at the typical corner, and it will not show up until post-route STA on a
design whose route converged, whose DRC was 0 and whose LVS matched.

**Three rewrites recover it, all equivalence-preserving, none touching the
spec.** The first two reduce the number of carry-propagate adds on the path;
the third is about the one that is left, and a run that applied only the first
two was measured through the front door still VIOLATING its sign-off corner,
with a single full-width ripple carry as the dominant term of its worst path
(vibe-ic#2228). Stopping after tw

…(truncated)
