git:20261105.f2bfad5 to git:20261106.a0a79f8

19 added, 122 removed. Audit A to A.

---

name: spec-validator

description: "Cross-check Datasheet, Application Note, and Spec for consistency. Detects pin name mismatches, register address conflicts, and unresolved TBD values. Also runs auto-quality scoring on DS (0-100) and AN (0-80). Triggers when: 'check consistency', 'validate docs', 'cross-check DS and AN', 'are the docs consistent', 'run spec validator', or before Checkpoint 1 gate. This is an automated pre-gate check — run before every Phase 1 to Phase 2 transition."

---

- # Spec Validator — Cross-Consistency + Quality Scoring

- Ensures that Datasheet, Application Note, and Specification are internally consistent and meet minimum quality thresholds before advancing to Phase 2 (Design).

- ## When to use

- - Before running checkpoint-gate for Phase 1 -> Phase 2

- - After generating or editing a datasheet or application note

- - When user says "check docs", "validate", "cross-check", "consistency"

- - Proactively before any Phase 2 tool invocation

- ## Tools

- > All four checks below are **enforced by deterministic programs**, not prose to

- > grade by hand. The exact criteria, weights and thresholds live in

- > `programs/ds_quality_check.py`, `programs/an_validator.py`,

- > `programs/spec_validator.py` and `programs/spec_conformance_check.py` so every

- > agent gets the identical verdict. **Run the program — do not re-grade the table

- > mentally.** All four are chip-AGNOSTIC, pure-stdlib, follow the

- > `main(argv)->int` 0/1/2 contract, and degrade to `MISSING`/`SKIP` (never a

- > false FAIL) on absent or unexpected input.

- ### 1. ds_quality_check.py — Datasheet (L1) Scoring (0-100)

- Scores a Markdown datasheet on 10 criteria (0-10 each: Features, Description,

- Pin Configuration, Absolute Maximum Ratings, Recommended Operating Conditions,

- Electrical Characteristics, Timing Diagrams, Block Diagram, Detailed

- Description + Register Map, Application Information). **Run it:**

- ```bash

- # single file or a project dir (auto-locates the datasheet)

- python3 programs/ds_quality_check.py phase1_spec/04_datasheet.md --json

- python3 programs/ds_quality_check.py <project_dir> --json

- ```

- Output: `{score, max:100, threshold:70, verdict, breakdown:[...]}`.

- **Checkpoint 1 threshold: score >= 70/100** (exit 0 = PASS, 1 = FAIL,

- 2 = MISSING/empty — treat MISSING as "datasheet not produced yet", not a fail).

- ### 2. an_validator.py — Application Note (AN) Scoring (0-80)

- Scores a Markdown application note on 8 criteria (0-10 each: Overview, Typical

- Application Circuit, External Component Selection, PCB Layout, Firmware Example,

- Design Calculations, FAQ, Competitive Comparison). **Run it:**

- ```bash

- python3 programs/an_validator.py phase1_spec/05_appnote.md --json

- python3 programs/an_validator.py <project_dir> --json

- ```

- Output: `{score, max:80, threshold:56, verdict, breakdown:[...]}`.

- **Checkpoint 1 threshold: score >= 56/80.**

- ### 3. spec_validator.py — DS↔AN Cross-Consistency Check

- Cross-checks identifiers between documents (DS Pin Configuration ↔ AN Typical

- Application Circuit; DS Register Map ↔ AN Firmware Example; and TBD/TODO/

- placeholder tokens that must be zero across all docs). Identifiers are parsed

- structurally from the docs — never compared against a hard-coded pin/register

- list — and a check is **SKIPPED** (not flagged) when either side lacks the

- section or parsable identifiers, so a sparse doc never produces a false

- mismatch. **Run it:**

- ```bash

- python3 programs/spec_validator.py \

- --ds phase1_spec/04_datasheet.md \

- --an phase1_spec/05_appnote.md \

- --spec phase1_spec/03_spec_confirmed.md --json

- # or auto-locate DS + AN inside a project dir:

- python3 programs/spec_validator.py <project_dir> --json

- ```

+ # Review specification consistency

- Output: `{verdict, error_count, findings:[...]}` with rules `pin-mismatch`,

- `register-mismatch`, `unresolved-tbd` (all ERROR) and `section-missing` (INFO/

- SKIP). **Checkpoint 1 threshold: 0 ERROR-level mismatches.**

+ Read the datasheet, application note and specification as the design inputs.

+ Compare their facts where the generated documents and RTL consumers use them.

- **AI judgment (keep):** a passing score is necessary, not sufficient. Still

- eyeball the `breakdown` for criteria that scored full marks on thin content

- (e.g. a register table with placeholder rows), and confirm any

- `section-missing` SKIP is genuinely "section not applicable for this IC class"

- rather than "section forgotten". Use `/datasheet-gen` to raise a low DS score.

+ - Match pin names, directions, widths and voltage domains.

+ - Compare register addresses, field widths, reset values and access behavior.

+ - Compare clock rates, timing units, protocol encoding and latency.

+ - Resolve contradictory limits, absent requirements and undocumented defaults.

+ - Check that examples exercise the stated normal, boundary and error cases.

- ### 4. spec_conformance_check.py — Spec↔RTL contract gate (once RTL exists)

+ Keep original source and PDK limits. Report the conflicting facts with their

+ source locations rather than resolving them through a quality score. When RTL

+ exists, run the normal native lint, simulation, formal or equivalence task for

+ the concrete requirement. An absent execution result is `NOT_MEASURED`.

- The checks above keep the *documents* consistent. Once RTL is drafted, this gate

- proves the *implementation* matches the declared contract — the failure that

- slips past pure structural lints (e.g. a spec that says "synchronous reset"

- while the RTL is asynchronous, or an interface whose ports drifted from the

- spec). It extracts the expected interface + reset semantics + output latency

- straight from the spec (natural-language bullets `- input d (8 bits)`, a

- markdown ```verilog module(...)``` header, or a JSON contract) — no hand-built

- port list — and diffs it against the RTL.

+ Read the selected rows in `<project>/reports/flow_engine.json` and open their

+ native `reports`. `flow/steps.json` names each current tool and

+ `flow/native_limits.json` retains its original limits. Review `tool_ran`,

+ `native_steps`, `native_metrics`, and each metric's value, operator and limit.

+ A missing native measurement is `NOT_MEASURED`. AI reviews the engineering

+ meaning of every result and fixes problems in the design, tool or plugin.

```bash

- # CLI

- python3 programs/spec_conformance_check.py --spec phase1_spec/04_datasheet.md \

- --rtl-dir phase2/stage1/rtl --top <module>

- # MCP (preferred in-flow)

- # eda_spec_conformance { spec, rtl_dir|verilog_files, top }

+ python3 programs/flow_engine.py report --project <project>

```

- Findings: `port-missing/extra/direction/width`, `reset-mode-spec-mismatch`,

- `reset-polarity-spec-mismatch` (all ERROR); `reset-not-found` (WARN);

- `latency-mismatch` (INFO). **Threshold: 0 ERROR.** If a `reset-*-spec-mismatch`

- fires, reconcile the spec wording against the reference/testbench before Phase 2 —

- a blind spec-faithful RTL will otherwise mismatch the bench.

- ## Workflow

- 1. Run `ds_quality_check.py` on the datasheet

- 2. Run `an_validator.py` on the application note

- 3. Run `spec_validator.py` to cross-check both (+ spec if available)

- 4. Once RTL exists, run `spec_conformance_check.py` (or `eda_spec_conformance`)

- to prove the RTL conforms to the spec's ports + reset + latency contract

- 5. If any check fails threshold, report findings and block Phase 2 entry

- 6. Log results via `vibe_ic_log.py`

- ## Output format

- Each tool outputs both human-readable text and `--json` machine-readable format.

- JSON outputs can be piped to `vibe_ic_log.py` for unified pipeline logging.

- ## Handoff

- - All checks pass -> `/checkpoint-gate` (Phase 1 -> Phase 2)

- - DS score low -> improve datasheet with `/datasheet-gen`

- - AN score low -> improve application note

- - Mismatches found -> fix inconsistencies before proceeding