Sidecar
This page lists every key of the sidecar: the file that holds the approved waivers and acknowledgements of one spec doc. Speccy writes no decision into the doc itself, so the doc keeps its own format.
waivers: - check: lint.sentence-length section: [Payment retries, Limits] reason: The sentence quotes the card network rule, and a split changes its meaning. section_hash: sha256:752d1754bd7b42a181cc8ec171e2e5999fbf1eadfab58904f84cca38ea8a984b requested_by: Nathantrace: - id: REQ-004 status: covered_by target: docs/sdd-notifications reason: The notification service sends the retry email, and its SDD covers it. acknowledged_by: Nathan - id: REQ-007 status: out_of_scope reason: The finance team reconciles refunds by hand this quarter. acknowledged_by: NathanWhere it lives
Section titled “Where it lives”The sidecar of the doc at <doc path> is .speccy/decisions/<doc path>.yaml. The doc path is relative to the root of the repo or the served folder. The sidecar of docs/sdd-payments.md is .speccy/decisions/docs/sdd-payments.md.yaml.
| Source | Where Speccy reads and writes the sidecar |
|---|---|
| A folder on disk | At the root of the served folder, where git sees it. |
| A GitHub source | Among the bundle’s files in Speccy. A publish writes it to the root of the repo. |
| A bundle made in Speccy | Among the bundle’s files, at the doc’s path in the bundle. |
A missing sidecar holds no decisions. Speccy writes an empty sidecar as an empty file. A scan and a review skip the sidecar, so it is never a spec doc.
The sidecar has four top-level keys. Each one is optional. In the tables, Needed marks a key without which Speccy ignores the entry.
| Key | Type | What it holds |
|---|---|---|
waivers |
list of waivers | The approved waivers of this doc. |
trace |
list of trace acknowledgements | The upstream trace IDs that this doc does not cover, each with a reason. |
standalone |
one standalone acknowledgement | The reason this doc has no upstream doc. |
upstream_changes |
list of upstream requests | The conflicts with a linked doc that the linked doc must fix. |
waivers
Section titled “waivers”Each waiver excuses one check in one section. One waiver covers every shortfall of that check there. A waiver of coherence.contradiction is different: it excuses one conflict. See A waiver of a conflict.
| Key | Type | Needed | What it holds |
|---|---|---|---|
check |
check slug | yes | The check that the waiver excuses. |
section |
list of headings | no | The heading path of the section. An empty list, [], or no section, is the whole doc. |
reason |
text | yes | Why the check does not apply here. |
section_hash |
sha256:<hex> |
yes, unless the waiver has check_hash |
The hash of the section at the time of the request. |
check_hash |
check:<hex> |
yes, for a whole-doc check | The hash of the check’s question and pass_when at the time of the request. It replaces section_hash. |
requested_by |
text | no | The person who asked for the waiver: a name or an email from the app, or a GitHub login from a reply command. |
conflict |
one conflict | no | For coherence.contradiction only: the one conflict that the waiver excuses. |
What Speccy writes depends on the check:
| Check | section |
Hash |
|---|---|---|
A rubric check that names a section in the profile |
The heading path of that section. | section_hash of the section with its subsections. |
A lint rule, or a check with scope: section |
The heading path of the finding. | section_hash of the section’s own text. |
A whole-doc check: a rubric check with no section and no scope: section |
[] |
check_hash |
A check of another stage that reads the whole doc, such as links.has-upstream |
[] |
section_hash of the whole doc after the frontmatter. |
A waiver of a whole-doc check looks like this:
waivers: - check: sdd.performance section: [] reason: The doc changes a nightly batch job, and no user waits for its result. check_hash: check:beafdbbc333bf7a6a832bada2b3f9350d1583bf326142639d56875554ed4fffd requested_by: NathanA waiver holds while its check and reason are not empty and its hash still matches:
- With
section_hash, the hash equals the hash of the section now. When the section changes, the waiver ends, and the check counts again. - With
check_hash, the hash equals the hash of the check in the profile now. An edit to the doc does not end the waiver. It ends when the profile changes thequestionor thepass_whenof the check. It also ends when a full review passes the check. When a later review fails the check again, the entry applies again.
The entry stays in the file. The app shows the waiver as ended, and it says why.
The sidecar names no approver. In the app, the approval records who approved. In a pull request, the merge records it.
A waiver of a conflict
Section titled “A waiver of a conflict”A coherence.contradiction finding names one conflict: a quote in this doc, and a quote in a linked doc that says a different thing. Its waiver binds to that conflict, so a new conflict in the same section stays open.
| Key | Type | Needed | What it holds |
|---|---|---|---|
with |
spec doc slug | yes | The linked doc. |
quote |
text | yes | The text of this doc that conflicts. |
with_quote |
text | yes | The text of the linked doc that it conflicts with. |
waivers: - check: coherence.contradiction section: [Payment retries, Timing] reason: The PRD changes to 10 days in the next release, and the product team agreed. section_hash: sha256:752d1754bd7b42a181cc8ec171e2e5999fbf1eadfab58904f84cca38ea8a984b requested_by: Nathan conflict: with: docs/prd-payments quote: The worker pays each refund within 10 working days. with_quote: The system MUST refund a card payment within 5 working days of the request.The waiver covers a finding when the check, the section, and the three keys of conflict match. Speccy compares the quotes without case, and it treats each run of spaces and line breaks as one space. The review model can quote the same text with such small changes from one run to the next. When the model quotes the conflict in other words, the waiver does not cover it. Ask for a new waiver.
The waiver also holds only while the section is the same, as the section_hash says.
A coherence.contradiction waiver with no conflict key covers each conflict in its section. Speccy wrote waivers in this form before it recorded the conflict, and they keep working. A new waiver always names its conflict.
Each entry answers a trace.coverage gap: one ID of an implements target that this doc does not name.
| Key | Type | Needed | What it holds |
|---|---|---|---|
id |
trace ID | yes | The upstream ID, such as REQ-004. |
status |
covered_by or out_of_scope |
yes | covered_by: another doc covers the ID. out_of_scope: no doc of this work covers it. |
target |
spec doc slug | with covered_by |
The doc that covers the ID. |
reason |
text | yes | Why this doc does not cover the ID. |
acknowledged_by |
text | no | The person who asked for the acknowledgement. |
An acknowledgement is about one upstream ID, not a section of this doc. An edit to this doc does not end it. The Traceability matrix shows each one with its reason.
standalone
Section titled “standalone”The standalone acknowledgement says that this doc has no upstream doc. With it, links.has-upstream passes, and the coherence checks of this doc do not apply.
| Key | Type | Needed | What it holds |
|---|---|---|---|
reason |
text | yes | Why the doc has no upstream doc. An empty reason counts as no acknowledgement. |
acknowledged_by |
text | no | The person who wrote the acknowledgement. |
This key lives in the sidecar only. Speccy ignores a standalone key in the frontmatter.
upstream_changes
Section titled “upstream_changes”Each entry is an upstream request: the answer “The linked doc must change” to one coherence.contradiction finding. While the request is open, the finding reads “Waiting on” the linked doc, and it does not block the verdict of this doc. The review of the linked doc gives it the MUST finding coherence.downstream-request. Upstream requests and send-backs explains the flow.
| Key | Type | Needed | What it holds |
|---|---|---|---|
conflict |
one conflict | yes | The conflict, with with, quote and with_quote, as in a waiver of a conflict. |
reason |
text | yes | Why the linked doc must change. Its author reads this. |
requested_by |
text | no | The person who asked. |
sent_back |
one send-back | no | The answer of the linked doc: this doc must change. |
A sent_back entry has these keys:
| Key | Type | Needed | What it holds |
|---|---|---|---|
reason |
text | yes | Why this doc must change. |
by |
text | no | The person who asked for the send-back. |
upstream_changes: - conflict: with: docs/prd-payments quote: The worker pays each refund within 10 working days. with_quote: The system MUST refund a card payment within 5 working days of the request. reason: The card network allows 10 days, and the shipped worker uses that. requested_by: Nathan sent_back: reason: Finance needs 5 days for the quarter close, so the worker must change. by: PriyaA sent_back key ends the request. The conflict blocks this doc again, and the finding shows the reason of the send-back. After a send-back, the conflict takes an edit or a waiver, and no second upstream request.
An entry also stops applying when an edit of either doc removes one of its quotes, because the conflict is gone. The entry stays in the file until a later decision about the same conflict writes over it.
The profile key coherence.upstream_pending: block makes an open request block the verdict of this doc too.
The section hash and the check hash
Section titled “The section hash and the check hash”section_hash is sha256: and the hex SHA-256 of the section’s own text:
- The text starts after the heading line, and it stops at the next heading of any level. A child section is not part of its parent’s text.
- For a rubric check that names a
section, the text goes on through the child sections. It stops at the next heading of the same or a higher level. - For
section: [], the text is the whole doc after the frontmatter. - Before the hash, Speccy changes each line ending to
\nand removes spaces and tabs at the end of each line. - Speccy also turns each run of blank lines into one blank line, and removes blank lines at the start and the end.
So an edit to the words of a section ends its waivers. A change to trailing spaces or blank lines does not.
check_hash is check: and the hex SHA-256 of the check’s question, one zero byte, and its pass_when. The doc text is not part of it.
Who writes it
Section titled “Who writes it”| Writer | What it writes |
|---|---|
| The app | A trace acknowledgement or a standalone acknowledgement, at once, with no approval. A waiver in local mode, at once. A waiver in hosted mode, or an upstream request, when the last approval that the profile’s waiver policy needs arrives. A send-back, and a waiver asked on the linked doc, go into the sidecar of the downstream doc. Speccy writes nothing into the sidecar of the linked doc. A withdrawal of a trace or standalone acknowledgement takes the entry out, with no approval. For a folder on disk, the write makes no new version, because the doc text does not change. |
| The GitHub Action | A waiver, a trace acknowledgement or a standalone acknowledgement, from a reply command. The Action commits the sidecar to the pull request’s branch. |
| You | Any entry. Speccy treats an entry you write by hand in the same way as its own. |
In the app, Mark it standalone on a links.has-upstream finding writes the standalone entry at once. Withdraw on the Traceability page takes a trace entry or the standalone entry out. Only a person who can edit the doc can withdraw an entry. The event log records who withdrew it. A withdrawal also takes out an entry that a reply command or a person wrote.
A pull request from a fork gives the Action no write token. The Action then prints the sidecar in its summary comment, and you commit it yourself. While a waiver is in the branch and not in the base branch, the summary comment gives the verdict with and without it.
A verification waiver never goes in the sidecar. It excuses one trace ID in one code repo, and the sidecar travels with the doc into every build.
When Speccy writes a waiver for a check and a section that the sidecar has already, the new entry replaces the old one. For coherence.contradiction, the conflict must match too, so one section can hold one waiver for each conflict. A trace acknowledgement replaces the one with the same id. An upstream request replaces the one with the same conflict.
Errors
Section titled “Errors”Speccy reads the sidecar strictly. An unknown key, or a value of the wrong type, stops the review of the doc:
.speccy/decisions/docs/sdd-payments.md.yaml: the sidecar does not parse: yaml: unmarshal errors: line 3: field approved_by not found in type source.Waiver.