SpecDoc privacy

This board emails digests of spec activity and opens pull requests on your behalf. What it stores and why:

What is stored

• Recipient email addresses, queued only while a digest is batched, taken from your SpecDoc account or GitHub profile.
• Queued activity details: spec titles, observed times, links, recipient reasons, and short public discussion excerpts with their author or visible signature. Digests omit notes that are private, limited, protected or deleted when delivery is checked.
• Discussion fingerprints, one-way hashes of comment messages, to detect discussion changes without retaining a second copy of their full text.
• Per-project subscription levels (watch, participating, disabled), tied to your GitHub-linked account, when you set them.
• Your chosen commit-author email, a global default and optional per-project override, when you set one in settings.
• Your chosen notification email, a global default and optional per-project override, when you pick a delivery address other than your account default in settings.
• Your verified GitHub email addresses, fetched with email permission at editor or board sign-in and saved in your linked SpecDoc account profile, with the primary address first. The board also holds them in your signed session cookie for the settings pickers. Account defaults use the primary verified address unless you choose an override.
• A one-way hash of any address that unsubscribed, so the opt-out is honored without keeping a readable list of who you are.
• Copies of a spec's published text at each status change, each publish, and each approval, an approval's copy labelled with that approver's login and taken when they press approve in the editor, so the board can show what changed since and tell an approver when the text moved past their approval. The approval itself is recorded here, not in the note.
• Personal access token hashes and metadata in the editor: the owning account, token name, permissions, creation and expiry times, last use, and revocation time. The token secret is displayed once when created and is not stored.
• Implementation review evidence and amendment proposals for projects that enable feedback: public GitHub PR descriptions, review discussion and author logins, relevant code patches, source identifiers and spec versions. Automatic-generation settings record the acting login and time.

Published in pull requests

Editor upgrades repair spec notes with review comments before their YAML header by moving those comments below the header. Comment text and per-character attribution are preserved, and note ownership and permissions stay unchanged. Existing revisions remain available.

When an approved spec opens a pull request, and again each time a re-approved spec publishes a revision, the git commit records an author and a Reviewed-by line for each approver and for each person who commented on the note. The generated spec map that rides in the same pull request is committed under the same author. These carry the email you selected in settings, or your account email if you selected none. Commit metadata is public and permanent in the target repository's history.

Reviewer credits use your commit-author email preference separately from notification delivery settings. Publication waits if a credited account has no email; signing in again refreshes its verified addresses.

Published by the read API

The board serves its spec corpus as JSON at /api/specs, unauthenticated, for tools outside the browser: spec text, author login and review counts, excluding any note HedgeDoc marks private, limited or protected. It reaches further than the board's own pages in two ways: it serves the full text of a spec rather than its first paragraph, and its revision endpoints serve the raw note, including review threads the board resolves away.

Finding implementers

Project approvers and board admins can search existing editor accounts by username or display name when assigning implementers. Results include account identifiers, usernames and display names. Search text is sent to the board as you type and may appear in request logs. The lookup does not save searches or results in browser storage or account preferences.

Personal access tokens

The editor also offers an authenticated note API. A personal access token can read raw notes, including frontmatter and review comments, within its owner's note permissions; a write token can create and edit notes as that owner. Edits retain attribution for unchanged text and attribute added text to that account. Tokens do not authorize review approvals.

Automated review

When a spec enters review, its note text may be sent to one or more language-model endpoints configured by the board operator, and the board writes the model's review comments back into the note. The board sends with it the project's approved top-level specs, and up to three approved specs it depends on, that depend on it, or that share its area, as published, so that the model can weigh the spec against what the project already settled. All of this is spec markdown only, no account data, and every document sent is a public note. Where the model reports that the spec under review contradicts one of those other specs, the finding is shown on the board card instead of being written into the note, and it does not block approval. Configured endpoints may be operated by third parties. A reported conflict is stored on the board, as the spec number, the sentence and the quoted line it points at, until the next review of that spec replaces it; nothing else from the model call is kept.

A board admin reviewing a checkpoint also sends every approved spec in that project to the same endpoint, to be checked for specs that overlap each other, and, for the checkpoint's changelog, the text of specs added since the last checkpoint and a diff excerpt of each revised one. This is published spec text only, no account data. The model's findings are shown to the admin and never written into a note; the ones the admin acknowledges are recorded in the checkpoint tag's message, which is public in the target repository.

When a project selects a feedback bot, merged implementation PR discussions, reviewer logins, relevant code patches and canonical spec text are sent to that configured endpoint to propose amendments. Sources and target specs must be public. Each proposal is written into the note as a suggestion under the bot's name, with a comment naming the pull request it came from, so it is as public as the note and appears in the spec API like any other note text. Nobody's login is written into the note. An approved spec returns to review until the suggestion is accepted or rejected. A project approver or board admin can turn automatic proposals off in settings.

A board admin can issue a bot a token instead of, or as well as, an endpoint. Whoever holds the token can read the raw text of public notes in that bot's projects, including review threads, and write comments, replies and suggestions into them under the bot's name, the same way the review bots do. The model behind a token runs wherever its holder runs it, typically on their own machine, and the board does not see where the text goes. The board stores only a hash of the token; revoking it on the bots page ends access.

Browser preferences

My specs and To review use the GitHub login of your signed-in board account. If you are signed out of the board, your browser can read your editor account's username to apply these filters.

The board keeps your layout, stage visibility and personal filter choices in your browser's local storage. In that tab's session storage it keeps the text you type into the board's filter box, and the ids of the specs its activity check reports as changed, so that pressing Refresh or changing a filter loses neither. These stay in that browser and are not stored in your account. Clear this site's browser data to remove them; what session storage holds also goes when the tab closes.

The layout, stage and personal filter choices are also written into the page address, so that a link you copy shows the board as you left it. They are sent to the board with every page load and with the check it makes for new activity every 30 seconds, and appear in its request logs; the person filter carries a login name. Text typed into the filter box narrows the page in your browser. It reaches the board, and the address, only when you search the full text. Remove filters from the address before sharing a link if you would rather not pass them on.

Retention

• Queued digest rows are deleted as soon as the email is sent.
• Discussion fingerprints are replaced at each poll and cleared after the note is deleted.
• Text snapshots are deleted with the note; an approval's snapshot goes when that approval is retracted.
• Editor mutation receipts store operation identifiers, request and content hashes, and permission results so retries do not repeat a write. They are deleted with the note; they do not retain another copy of its text.
• Opt-out entries are kept so the unsubscribe keeps being honored.
• Subscription levels, your commit-author email, and your notification email persist until you change them.
• The verified-email list lives only in your session cookie and is gone when you sign out or it expires.
• Personal access token records remain visible after expiry or revocation and are deleted when their owning editor account is deleted. Revocation stops further authentication immediately.
• Dismissed or incorporated amendment payloads are cleared after 90 days. Unreferenced review evidence is cleared after 90 days. Compact source identifiers, hashes and decision records remain to avoid repeating previously considered suggestions; accepting a proposal for editing keeps it open until a later decision.

Lawful basis

Legitimate interest: notifying collaborators about specs they own, edited, or chose to watch, and attributing spec commits to their author and reviewers. Every email carries a one-click unsubscribe.

Opt out and erasure

Use the unsubscribe link in any digest to stop all email. On the settings page, set every project back to Participating to clear subscriptions and set your author and notification emails back to Account default to clear those preferences. For anything else, contact privacy@josie.cloud.

A recipient with no linked SpecDoc account can unsubscribe from any email, but must sign in once to re-enable it.

Back to the board