Skip to content

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: Nathan
trace:
- 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: Nathan

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.

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: Nathan

A 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 the question or the pass_when of 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 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.

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.

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: Priya

A 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.

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 \n and 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.

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.

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.