release: prepare v0.0.1-rc.4

process/dirtyroom_dossier_schema.md

@@ -1,56 +1,30 @@
 # Dirty-Room Dossier Schema
 
-Each dossier file is TOML and must include these fields.
+Each dossier is a TOML file that captures sanitized protocol evidence for one PID and one operation group.
 
 ## Required Fields
-- `dossier_id`: stable identifier, e.g. `DOS-5200-CORE`.
-- `pid_hex`: target PID in hex (`0xNNNN`).
-- `operation_group`: logical grouping (`CoreDiag`, `ModeProfileRead`, `FirmwarePreflight`, etc).
-- `command_id`: array of command IDs scoped by this dossier.
-- `request_shape`: sanitized request structure summary.
-- `response_shape`: sanitized response structure summary.
-- `validator_rules`: array of response validation constraints.
-- `retry_behavior`: retry and timeout behavior summary.
-- `failure_signatures`: array of known failure signatures.
-- `evidence_source`: `static` for this wave.
-- `confidence`: `inferred` or `confirmed`.
-- `requirement_ids`: array of linked requirement IDs.
-- `state_machine`: table with `pre_state`, `action`, `post_state`, and `invalid_transitions`.
-- `runtime_placeholder`: table with `required` and `evidence_needed`.
-- `hardware_placeholder`: table with `required` and `evidence_needed`.
+
+- `dossier_id`
+- `pid_hex`
+- `operation_group`
+- `command_id`
+- `request_shape`
+- `response_shape`
+- `validator_rules`
+- `retry_behavior`
+- `failure_signatures`
+- `evidence_source`
+- `confidence`
+- `requirement_ids`
+- `state_machine`
+- `runtime_placeholder`
+- `hardware_placeholder`
 
 ## Optional Fields
-- `class_family`: static class-family grouping hints.
-- `notes`: additional sanitized context.
 
-## Example
-```toml
-dossier_id = "DOS-5200-CORE"
-pid_hex = "0x5200"
-operation_group = "CoreDiag"
-command_id = ["GetPid", "GetReportRevision", "GetControllerVersion", "Version", "Idle"]
-request_shape = "64-byte HID report, command byte in report[1], PID-specific gating outside payload"
-response_shape = "short status header plus optional payload bytes"
-validator_rules = ["byte0 == 0x02", "response length >= 4"]
-retry_behavior = "retry up to configured max attempts on timeout/malformed response"
-failure_signatures = ["timeout", "malformed response", "unsupported command for pid"]
-evidence_source = "static"
-confidence = "inferred"
-requirement_ids = ["REQ-DR-001", "REQ-PROM-001", "REQ-PID-002"]
-class_family = "JP/Handshake path"
-notes = "candidate-readonly in this wave"
+- `class_family`
+- `notes`
 
-[state_machine]
-pre_state = "DeviceConnected"
-action = "Run core diagnostics reads"
-post_state = "DeviceIdentified"
-invalid_transitions = ["NoDevice", "TransportClosed", "BootloaderOnly"]
+## Authoring Rule
 
-[runtime_placeholder]
-required = true
-evidence_needed = ["runtime request/response captures", "error signature examples"]
-
-[hardware_placeholder]
-required = true
-evidence_needed = ["physical read validation", "repeatability checks"]
-```
+Prefer short, structure-level descriptions over long prose. The dossier should be good enough to guide clean implementation and testing without embedding dirty-room source text.