diff --git a/docs/README.md b/docs/README.md index beb6e53..4b891ba 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,8 +15,8 @@ Start here if you're considering a feature contribution or want to understand Ja - **[Timing Correctness](timing-correctness.md)**: Scoped requirements for timing accuracy, validation, and the forthcoming timing IR. - **[Timing Model Extensions](timing-model-extensions.md)**: Pre-spike design notes for δ(T) dynamic delay, clock-tree skew, and wire delay at scale. Formalised in ADR 0007. - **[Post-Phase-0 Roadmap](plans/post-phase-0-roadmap.md)**: Sequencing of Phase 1+ work covering structured timing output (ADR 0008) and timing model fidelity (ADR 0007). (OpenTimer integration was originally Phase 1's centrepiece; ADR 0003 was Superseded by the spike — OpenSTA out of process is now the sole STA path per ADR 0001.) -- **[Architecture Decision Records](adr/)**: Design decisions and their rationale (numbered, per-decision). -- **[Implementation Plans](plans/)**: Phased implementation plans with entry and exit criteria. +- **[Architecture Decision Records](adr/README.md)**: Design decisions and their rationale (numbered, per-decision). See the index for status and how the ADRs relate. +- **[Implementation Plans](plans/README.md)**: Phased implementation plans with entry and exit criteria. See the index for status and reading order. - **[Spikes](spikes/)**: Time-boxed experiments and their outcomes. ### Core Documentation diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index d98288a..2c9ff5f 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -10,3 +10,24 @@ - [Adding a New PDK](adding-a-pdk.md) - [Troubleshooting VCD](troubleshooting-vcd.md) - [Handoff Discipline](handoff-discipline.md) + +# Decisions & plans + +- [Architecture Decision Records](adr/README.md) + - [0001 — OpenSTA as the timing correctness oracle](adr/0001-opensta-as-oracle.md) + - [0002 — Timing intermediate representation](adr/0002-timing-ir.md) + - [0003 — OpenTimer as in-process reference STA (Superseded)](adr/0003-opentimer-primary-sta.md) + - [0004 — Private PDK testing track](adr/0004-private-pdk-testing.md) + - [0005 — OpenSTA vendoring and test-corpus strategy](adr/0005-opensta-vendoring-and-corpus.md) + - [0006 — SDF preprocessing model](adr/0006-sdf-preprocessing-model.md) + - [0007 — Timing model fidelity roadmap (Proposed)](adr/0007-timing-model-fidelity-roadmap.md) + - [0008 — Structured timing output as first-class deliverable](adr/0008-structured-timing-output.md) +- [Implementation Plans](plans/README.md) + - [Post-Phase-0 Roadmap](plans/post-phase-0-roadmap.md) + - [GF180MCU PDK enablement](plans/gf180mcu-enablement.md) + - [Phase 0: Timing IR and OpenSTA oracle](plans/phase-0-ir-and-oracle.md) + - [WS2: opensta-to-ir](plans/ws2-opensta-to-ir.md) + - [WS3: delete SDF parser](plans/ws3-delete-sdf-parser.md) + - [WS3 follow-up: cosim --sdf](plans/ws3-cosim-sdf-followup.md) + - [Multi-clock and stimulus architecture](plans/multi-clock-and-stimulus-architecture.md) +- [Spike — OpenTimer on SKY130](spikes/opentimer-sky130.md) diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..6e44bb5 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,54 @@ +# Architecture Decision Records + +ADRs capture decisions worth understanding later: the context, the +options considered, and the rationale for the choice. They are +numbered, append-only, and never silently rewritten — if a decision +changes, supersede the old ADR with a new one and update the status. + +## Status legend + +- **Accepted / Approved** — current, in effect. +- **Proposed** — drafted, not yet ratified. +- **Superseded** — historical, replaced by a later ADR or by a spike + outcome; kept for the audit trail. + +## Index + +| # | Title | Status | +|---|---|---| +| [0001](0001-opensta-as-oracle.md) | OpenSTA as the timing correctness oracle and sole STA path | Accepted (scope expanded 2026-05-01) | +| [0002](0002-timing-ir.md) | Timing intermediate representation | Accepted | +| [0003](0003-opentimer-primary-sta.md) | OpenTimer as in-process reference STA | Superseded (2026-05-01) — spike failed; OpenSTA subprocess only | +| [0004](0004-private-pdk-testing.md) | Private PDK testing track | Accepted | +| [0005](0005-opensta-vendoring-and-corpus.md) | OpenSTA vendoring and test-corpus strategy | Accepted | +| [0006](0006-sdf-preprocessing-model.md) | SDF preprocessing model and interim-to-release cutover | Accepted (amended 2026-05-02) | +| [0007](0007-timing-model-fidelity-roadmap.md) | Timing model fidelity roadmap | Proposed | +| [0008](0008-structured-timing-output.md) | Structured timing output as first-class deliverable | Approved | + +## How the ADRs relate + +- **0001 / 0003 / 0005 / 0006** describe the timing oracle stack: + OpenSTA as the ground truth (0001), vendored at a pinned revision + with its own corpus reused (0005), driving SDF preprocessing + out-of-process (0006). The earlier OpenTimer in-process plan (0003) + was retired after the spike ([`../spikes/opentimer-sky130.md`](../spikes/opentimer-sky130.md)). +- **0002** is the data contract those tools talk over — a JSON timing + IR consumed by Jacquard, produced by `opensta-to-ir`. +- **0004** governs how PDK-specific testing happens for NDA-bound + contributors without leaking files into the public repo. +- **0007 / 0008** are the forward-looking pair: 0008 (Approved) + defines the structured timing output Jacquard owes downstream + flows; 0007 (Proposed) sketches the model-fidelity work needed to + back those outputs at scale (δ(T), clock-tree skew, wire delay). + Scheduling for both lives in + [`../plans/post-phase-0-roadmap.md`](../plans/post-phase-0-roadmap.md). + +## Adding a new ADR + +1. Pick the next number (highest existing + 1). +2. Filename: `NNNN-short-kebab-title.md`. +3. Start with `# ADR NNNN — ` and a `**Status:**` line. +4. Standard sections: Context, Decision, Consequences. Add Amendment + blocks dated when the decision is revisited; do not rewrite + accepted history. +5. Add the row to the table above. diff --git a/docs/plans/README.md b/docs/plans/README.md new file mode 100644 index 0000000..74049bf --- /dev/null +++ b/docs/plans/README.md @@ -0,0 +1,55 @@ +# Implementation Plans + +Phased implementation plans with entry and exit criteria. Plans live +here when the work spans multiple commits and needs an explicit +scheduling artefact; once shipped, the plan is kept as a historical +record (Status flipped to *Implemented*) rather than deleted, so the +phasing is recoverable later. + +For short-lived working memory between sessions, see +[`../handoff-discipline.md`](../handoff-discipline.md) — that lives +in `docs/handoffs/` and is deliberately kept separate from the +persistent plans here. + +## Status legend + +- **Active** — currently being worked on or scheduled. +- **Implemented** — shipped; kept as historical record. +- **Deferred** — captured for future work; not currently scheduled. +- **Exploratory** — architectural thinking captured ahead of demand. + +## Index + +| Plan | Status | +|---|---| +| [Post-Phase-0 Roadmap](post-phase-0-roadmap.md) | Active — scheduling doc for ADRs 0007 and 0008 | +| [GF180MCU PDK enablement](gf180mcu-enablement.md) | Mostly implemented — Phases 0–6 shipped; Phase 7 deferred | +| [Phase 0: Timing IR and OpenSTA oracle](phase-0-ir-and-oracle.md) | Implemented — historical record | +| [WS2: `opensta-to-ir`](ws2-opensta-to-ir.md) | Implemented — historical record | +| [WS3: delete SDF parser + interim runtime hook](ws3-delete-sdf-parser.md) | Implemented — historical record (see ADR 0006 Amendment) | +| [WS3 follow-up: re-add cosim `--sdf` via `opensta-to-ir`](ws3-cosim-sdf-followup.md) | Deferred | +| [Multi-clock and stimulus architecture](multi-clock-and-stimulus-architecture.md) | Exploratory — demand-driven | + +## Reading order for new contributors + +If you want to understand how the timing stack got to where it is: + +1. [`phase-0-ir-and-oracle.md`](phase-0-ir-and-oracle.md) — the + umbrella plan, with the five work streams (WS1–WS5). +2. [`ws2-opensta-to-ir.md`](ws2-opensta-to-ir.md) and + [`ws3-delete-sdf-parser.md`](ws3-delete-sdf-parser.md) — the + per-work-stream detail for the IR producer and the SDF parser + removal. +3. [`post-phase-0-roadmap.md`](post-phase-0-roadmap.md) — what comes + next, sequenced against the ADRs. + +## Adding a new plan + +1. Filename: short kebab-case (`<topic>.md` or + `<ws-or-phase>-<topic>.md`). +2. Start with `# Plan — <title>` and a `**Status:**` line. +3. Where the plan executes a specific ADR or work stream, name them + in a `**Predecessors:**` / `**ADRs:**` block near the top so the + dependency graph is explicit. +4. Add the row to the table above. When the plan ships, change the + status in the file and here in the same commit.