git:20260908.d2bb58e to git:20260908.91ee09b

- description: Use when transcribing an intent document into the requirements ledger, deriving the partition, design docs and constraints from it, or updating them from rework feedback; not for RTL implementation or verification.

- source of truth. You dispatch and hold no document body: the intent document, the ledger,

- `design.md` and every `<child>.md` are read and written only inside sub-Task contexts.

- Read `{workdir}/dispatch.json` for this round's inputs: its `inputs` table maps each upstream key to a location, so `<key>/<subpath>` is how you address one. The only input is the intent tree, the container `<intent>/`: `brainstorm.md`, in whatever shape the engineer wrote it, plus whatever the engineer delivered with it and the document names as authoritative. Frozen for the run. The document is read whole only by the transcriber and the requirements reviewer; another file in the container is read by whoever a row pointing at it concerns.

- | `manifest.json` | The child partition: `module` + `children[]` (`name` / `doc` / `rtl_modules[]`) |

- | `design.md` | The decisions made around the ledger: architecture, partition rationale, inter-module behaviour contract, timing scenarios and waveforms (template: `references/design-template.md`) |

- | `children/<child>.md × N` | Per-child sub-design (template: `references/child-design-template.md`); `children/` leaves as one tree |

- | `clocks.json`, `top-io.json`, `interconnects.json` | The boundary: clocks, top-level ports, cut edges |

- | `spec-review/decisions.md` | The user's rulings at both gates, in their words. It accumulates across rounds — a ruling this round did not revisit still stands, so it is carried forward and appended to, never rewritten |

- | `spec-review/findings/` | `requirements.md` (the ledger against the intent document) and one review per child. This round's record: it does not carry into the next round, so a review on disk is always about what is on disk now |

- - **Sub-Task `STATUS: BLOCKED`:** a crash, not a `fail` verdict. Finalize with a `--fail-reason` listing the failed children — it lands in the envelope's `stage_specific.fail_reason` — and leave per-child re-dispatch to a repair round.

- - **`caused_by` present — failures downstream are waiting on this stage.** Each entry is one failing run's own `result.json`, and a round scheduled for some other reason carries them too: answer them in this round. This stage already shipped, and rtl-design / simulation-plan consumed the manifest, so the partition is not this round's to change. Scope is the union of `dispatch.json`'s `scope` and what the `caused_by` envelopes attribute; Read each envelope once. Dispatch one repair sub-Task over the decisions (`design.md`, the children, the sidecars), then pick up at **`check-crossrefs`** and run through to finalize: the authoring dispatches are skipped, but the join and the constraints must re-verify against what changed, and the child reviews re-run so the promoted review is never stale. The ledger is not re-transcribed: the intent document is frozen, and a row changes only by a human's ruling.

- Dispatch one Level-1 sub-Task per `references/decompose-task-contract.md`. It reads `requirements.json`, not the intent document, and writes `manifest.json`, `design.md`, `clocks.json`, `top-io.json`, `interconnects.json`. The author holds the rows and their ids and nothing else, so the design cites requirements rather than restating them.

-

- **Gate, script.** Run `derive-ports` to compute each child's inter-module ports, the `interconnects.json` wires whose producers or consumers include one of that child's `rtl_modules`:

-

- ```bash

- python3 <skill>/scripts/spec/__main__.py derive-ports --workdir {workdir}

- ```

-

- It also decides the top-partition purity rule, since this is the last moment the partition is still editable. On success the port map is on stdout, and the child sub-designs inject it. A non-zero exit names the defect on stderr; every one of them routes a decompose rework sub-Task.

- ### Requirements review

- Dispatch one Level-1 reviewer per `references/requirements-review-task-contract.md`. It reads the intent document, the ledger, the three sidecars and `design.md`, and writes `spec-review/findings/requirements.md`: what the document states that no row carries, what a row states that the document does not, which sidecar entries no row supports, where `design.md` contradicts or restates a row.

- **Gate, human — the ledger and partition gate.** Path-handoff, echoing no body, with four exceptions the gate view already holds verbatim: the `unassignable` rows with their `note`, the `outside` rows, the `human` rows, and the rows carrying a `target`. Add the `requirements.md` path, the N-child summary from manifest metadata (`Grep manifest.children[].{name,rtl_modules}`) plus the `derive-ports` map, and the `design.md` path.

- What the user decides here: every `unassignable` row (how it is measured, who judges it, or that it is not a requirement, in which case it becomes `none` with the reason in `note`); each `human` row, which they judge now from the documents in front of them; the partition. Write each ruling to `spec-review/decisions.md` in **their words, not yours**, then dispatch a transcribe repair sub-Task that edits the rows it names — nothing outside a sub-Task edits an artifact. After any edit to the ledger, re-run `check-ledger` and the requirements review. A reported omission or a partition change re-enters at transcribe or decompose.

- ### Child sub-designs (×N)

- Dispatch one sub-Task per child, each writing `children/<child>.md` per `references/child-design-template.md`, and alongside them one sub-Task writing `check-hints.json` per `references/check-hints-task-contract.md`. Inject each child's wire list from `derive-ports`; the child adds any top-IO ports it drives or reads. The hints are authored here rather than earlier because a row the human just ruled on can have become one simulation judges.

- **Gate, script.** Run `check-crossrefs`. N children authored their docs and check hints in parallel, so it reports what only a join can see: a name one of them wrote that resolves nowhere, a target nobody claimed, a hint naming a row simulation does not judge, a row simulation judges that no hint names.

- The verdict is structured on stdout: exit 0 clean, exit 1 the join found something. A non-zero exit with no verdict on stdout is exit 2 — a program exception, BLOCKED with the reason on stderr, most often a child doc the manifest names and nobody has written yet. **Fix nothing yourself.** Each disagreement names both sides, and which of the two is wrong is a judgment: the child may have mistyped a port, or the boundary may be missing it. Decide that, then route the rework to whoever authored that file, decompose for a sidecar and the affected child for a `<child>.md` or its check hints.

- It generates `constraints/<TOP>.{sdc,sgdc}` from `clocks.json` + `top-io.json`. Running it here, before the human gate, surfaces defects no cross-file join can see (the exactly-one-`primary` rule, clock-name collisions) while a rework is still cheap. It reads only the boundary sidecars, so a defect it reports on stderr routes to decompose.

- ### Child reviews (×N)

- Dispatch one Level-1 reviewer per `manifest.children[]` per `references/child-review-task-contract.md`, passing paths. Each writes its own `spec-review/findings/<child>.md`.

- **Handoff, not a gate.** Give the user the paths, echoing no body: `design.md`, each `children/<child>.md`, the `check-crossrefs` verdict, one `spec-review/findings/<child>.md` per child. You do not summarize the findings, rank them, or decide which ones matter: a review relayed through your summary is your judgment wearing the reviewer's name.

- Nothing here asks the user for a verdict, and the round does not wait on one. What the reviews reach for is the engineering soundness no script can — port roles, reset polarity, clock relationships, whether the children realize the rows they cite — and endorsing that is `kernel.py pin`, which anchors to the review's content and is what `signoff` refuses without. A blocking finding nobody acts on therefore leaves the module unsignable rather than shipping under a word typed to keep the round moving.

- Act on what they say: a body change re-enters at the child sub-designs, a partition change at decompose, and a finding they tell you to accept as-is goes to `spec-review/decisions.md` in **their words, not yours**, so the reasoning travels with the review it overrode. A round that cannot deliver at all closes below with `--fail-reason`.