Waivers and the sidecar
This page explains waivers and acknowledgements, where Speccy keeps them, and when a waiver ends.
A waiver
Section titled “A waiver”A waiver is an approved exception for one check in one section, with a reason. In the app, the control for a waiver is Ship it open: the gap is real, and the doc ships with it. A valid waiver takes its finding out of the verdict, and the score counts the check as passed. The reason must have 20 characters or more, so an approver can judge it.
A waiver covers a check, not a finding. A failed rubric check gives one finding for each shortfall, and one waiver covers every shortfall of that check in that section. A new finding of the same check in the same section falls under the same waiver.
What a waiver binds to depends on the check:
- A rubric check that names a section. The waiver binds to that section with its subsections. Most rubric checks of the built-in profiles name a section.
- A lint rule, or a check with
scope: section. The waiver binds to the section of the finding, without its subsections. - A whole-doc check. A rubric check that names no section, and does not have
scope: section, is a whole-doc check. Its waiver binds to the check, not to the doc text. A check that names a heading the doc does not have is also a whole-doc check for that doc. - A check of another stage that reads the whole doc, such as
links.has-upstream. The waiver binds to the whole doc body. coherence.contradiction. The waiver binds to the section of the finding and to the one conflict that the finding names. The conflict is the linked doc, the quote in this doc, and the quote in the linked doc. A new conflict in the same section stays open, and it needs its own waiver. Speccy ignores case and extra spaces when it compares the quotes, so a small change in how the model quotes the text keeps the waiver. A conflict quoted in other words needs a new waiver. A later review keeps the quotes of a conflict that it finds again, so the waiver still matches. See A conflict from run to run.
A waiver is not the answer for a finding that does not apply to this doc. Answer Not needed on the questions screen for that. Not needed takes a reason of at least 10 characters, and it closes at once with no approval.
Three kinds of finding take no waiver. An INFO finding never changes the verdict, so it needs none. A coverage gap takes an answer instead: an acknowledgement, or a reference to the trace ID in the doc. A MUST rubric check that the reviewer gave no answer for takes another review: only an answer clears it.
The waiver policy
Section titled “The waiver policy”In hosted mode, the profile says who may approve a waiver. waivers.should applies to a SHOULD finding, and waivers.must to a MUST finding. A check can set its own waiver policy, and that policy wins.
| Policy | Who approves |
|---|---|
any_member |
Any member of the workspace. |
non_author |
Any person who is not an author of the bundle. |
n_approvals |
N different people who are not authors. The waiver holds after the last of them approves. |
maintainer |
A maintainer of the profile, or an admin. |
forbidden |
Nobody. Speccy refuses Ship it open and Not needed for the check, and the doc needs a fix. |
The built-in profiles use non_author for SHOULD and maintainer for MUST.
A person who can approve a waiver can also reject it. To reject it, the approver gives a decision reason of 20 characters or more, so the author knows what to change. The request waits in the inbox of each approver, and at the top of the questions screen, under Waiting for your decision.
In local mode, you are the only person, and you are the approver. Ship it open closes at once, and Speccy writes the waiver to the sidecar. This applies to verification waivers too. Ask for and approve a waiver shows each step.
A waiver that people approve again and again points at a limit that is wrong. Change the limit in the profile instead.
The sidecar
Section titled “The sidecar”The sidecar is the file .speccy/decisions/<doc path>.yaml. It holds the approved waivers and acknowledgements of one spec doc. The doc path is the path of the spec doc from the root of the repo. The sidecar of docs/sdd-retries.md is .speccy/decisions/docs/sdd-retries.md.yaml.
waivers: - check: lint.sentence-length section: [Payment retries, Failure modes] reason: The provider's error table quotes its messages word for word. section_hash: sha256:2e9c2d5ef71e25853f034c7f8b7d908d29ba51040ba19192b170e59a7395fc27 requested_by: nathantrace: - id: REQ-002 status: out_of_scope reason: The mail service sends every customer email. acknowledged_by: nathanWhen an approver gives the final approval, Speccy writes the entry into the sidecar. An entry that needs no approval goes into the sidecar at once. The doc itself does not change. The Sidecar format lists each key.
Why decisions live in the sidecar
Section titled “Why decisions live in the sidecar”Speccy does not own the format of your doc, so it writes no decision into it. The sidecar sits next to the docs, in the same repo:
- Decisions travel with git. A branch, a pull request and a merge carry the decisions with the text they excuse.
- A reviewer sees them. A new waiver shows in the diff of a pull request, and branch protection decides who may merge it.
- Each tool reads the same file. The app,
speccy reviewand the GitHub Action read one sidecar, so they give one verdict.
Speccy honours a waiver that a person writes into the sidecar by hand, in the same way. It checks the reason, and the section hash or the check hash. An unknown key in a sidecar is an error, so a typo cannot pass without a word.
A reply command in a pull request also writes to the sidecar. The next run of the Action commits the entry to the branch of the pull request. Reply commands lists them.
A change to the sidecar lints the spec doc again, so an approved waiver changes the verdict at once. For a doc in a GitHub source, the sidecar is a file of the bundle version, and Publish puts it in the repo.
Heading path, section hash and check hash
Section titled “Heading path, section hash and check hash”A waiver names its section with a heading path: the list of headings down to that section, such as [Payment retries, Failure modes]. The doc needs no trace IDs for this.
The section hash is a SHA-256 of the text of the section at the time of the request. It covers the text under the heading, down to the first child heading. For a check that names a section, it covers the subsections too. Before it hashes, Speccy removes trailing spaces, turns each line ending into one form, and folds runs of blank lines into one. An empty heading path stands for the whole doc body after the frontmatter.
So the hash follows these rules:
- A change of trailing spaces or blank lines keeps the waiver.
- A change in a child section keeps the waiver of the parent section, unless the check names the parent section.
- A change of one word in the section ends the waiver.
- A new heading title changes the heading path, so the waiver no longer matches a section.
A waiver of a whole-doc check has no section hash. It has an empty heading path and a check hash: a SHA-256 of the question and the pass_when of the check. The doc text is not part of it, so an edit does not end the waiver.
Ended waivers
Section titled “Ended waivers”Each new version of a spec doc tests the approved waivers. When the section hash differs, Speccy ends the waiver, and its status becomes invalidated. The next lint counts the finding in the verdict again. Ask for a new waiver if the reason still holds.
The entry stays in the sidecar. It excuses nothing while the text of the section differs from the text it hashed. When the section returns to exactly that text, the entry applies again, and the waiver’s status becomes approved again. The sidecar decides, so the app and CI give the same verdict.
A waiver of a whole-doc check ends in two other cases:
- A full review passes the check. Nothing is left to excuse. When a later review fails the check again, the sidecar entry applies again, and the status becomes approved again.
- The profile changes the
questionor thepass_whenof the check. The check hash then differs. Ask for a new waiver.
The app says why a waiver ended: the section changed, a review passed the check, or the profile changed the check.
A section can also change between the request and the approval. The approval then fails with “The section changed after the request, so this waiver no longer fits it. Ask for a new waiver.” For a whole-doc check, the approval fails when the profile changed the check after the request.
Acknowledgements
Section titled “Acknowledgements”An acknowledgement is an author statement that a link or a trace item is absent on purpose. It uses the waiver mechanism: a reason of at least 20 characters and a record in the sidecar. It is a statement of scope or fact, not an exception. So it needs no approval, in local mode and in hosted mode. It closes the finding at once. A profile policy forbidden for the check still refuses it. The sidecar has two kinds.
Standalone says that the doc has no upstream doc. It meets the links.has-upstream check, and coverage, restatement and contradiction no longer apply to the doc.
standalone: reason: Internal change to storage. No product change, so no PRD. acknowledged_by: nathanIn the app, Mark it standalone on a links.has-upstream finding, or on its item on the questions screen, writes a standalone acknowledgement. It takes a reason of at least 20 characters. Speccy writes standalone: to the sidecar at once, and links.has-upstream passes. A standalone acknowledgement also comes from the reply command /speccy ack <reason> on a links.has-upstream finding, or from an edit of the sidecar.
Trace answers a coverage gap for one upstream trace ID. Its status is out_of_scope, or covered_by with the target doc that covers the ID. It closes the trace.coverage gap, and the matrix shows the answer with its reason. In the app, Another doc covers it and Out of scope write the trace: entry at once.
An acknowledgement is about the whole doc or an upstream ID, not a section of this doc. An edit of the doc does not end it.
Before this rule, an acknowledgement waited for approval as a waiver does. On upgrade, Speccy approves each acknowledgement request that still waits. The actor is “speccy”, and the note is “approval no longer needed”. Speccy writes the sidecar entry of each one, and the request leaves each inbox. Traceability explains coverage and the matrix.
Upstream requests and send-backs
Section titled “Upstream requests and send-backs”A coherence.contradiction finding is a conflict between this doc and a doc it links to. A waiver says that the conflict is acceptable. Sometimes the conflict is not acceptable, and this doc is right. Then only the author of the linked doc can fix the conflict. For this case, the finding takes a second answer: The linked doc must change.
This answer is an upstream request. It uses the waiver mechanism: a reason of 20 characters or more, and the waiver policy of coherence.contradiction. The approval writes the request into the sidecar of this doc, under upstream_changes:
upstream_changes: - conflict: with: prd-payments quote: The retry limit is 3. with_quote: The retry limit is 5. reason: The shipped code stops after 3 retries, and support agreed. requested_by: nathanAfter the approval, these things occur:
- The finding stays on this doc and reads “Waiting on” the linked doc. It does not block the verdict, so this doc can be Build Ready. A coding agent follows this doc.
- The review of the linked doc reads the sidecar of each spec doc that links to it. Each open upstream request gives the linked doc a MUST finding,
coherence.downstream-request. The finding quotes both docs and gives the reason. A pull request review of the linked doc posts this finding on the quoted line, as it posts any MUST finding. - Speccy writes nothing into the linked doc, its sidecar or its repo.
A team that wants the conflict to block until the linked doc changes sets coherence.upstream_pending: block in the profile. The default is allow.
The author of the linked doc has three answers:
- Edit the linked doc. When an edit of either doc removes a quote of the conflict, the conflict closes on both docs, and the upstream request ends.
- Ship it open. A waiver of the conflict on either doc says that the conflict is acceptable. It closes the conflict on both docs. A waiver asked on the linked doc goes into the sidecar of the downstream doc, as a waiver of
coherence.contradiction. - The downstream doc must change. This answer is a send-back. It takes a reason and the same approval policy. An upstream request and a send-back wait for approval in both modes. The approval writes the send-back into the upstream request, in the sidecar of the downstream doc. The request ends, and the conflict blocks the downstream doc again. The finding there shows the reason of the send-back.
After a send-back, the conflict takes no more answers of this kind. It needs an edit or a waiver.
An ended request stays in the sidecar until a later decision about the same conflict writes over it, as an ended waiver does. The waiver list of the doc says why it ended: the linked doc sent it back, or an edit closed the conflict.
A conflict from run to run
Section titled “A conflict from run to run”A conflict keeps its identity from one full review to the next. Its identity is the linked doc and the two quotes, as in the conflict key of a waiver. A waiver and an upstream request of a conflict match it by this identity.
The model often words the same conflict in other ways. After each new answer, a separate small call matches each new conflict with the conflicts of the last full review. A conflict that matches keeps the earlier quotes. An earlier conflict that the review does not find again stays, as a carried finding, while both of its quotes are in their docs. A conflict ends only when an edit removes one of its quotes. A change in the answer of the model does not end it.
Withdrawn acknowledgements
Section titled “Withdrawn acknowledgements”A person who can edit the spec doc withdraws an acknowledgement. Withdraw sits on an acknowledged cell of the traceability matrix, and on the “Standalone (acknowledged)” badge of the Traceability page. A withdrawal takes effect at once, with no approval, because it only makes the verdict stricter.
Speccy takes the entry out of the sidecar with the same write that wrote it. For a doc in a GitHub source, the change is a draft until you publish it. The next lint counts the finding in the verdict again. The event log of the acknowledgement records who withdrew it, and the waiver list shows its status as withdrawn. To close the finding again, answer it again.
Verification waivers stay out of the sidecar
Section titled “Verification waivers stay out of the sidecar”A verification waiver excuses one trace ID in one code repo, after a verification run. It follows the same policy and ends when the section of the requirement changes. It never goes in the sidecar, because the sidecar travels with the doc into every build of it. Handoffs and build reports explains verification runs.