This page lists each key that a profile file can hold. Speccy checks a profile against this schema when it loads the file, and speccy profile validate <file> checks one file. An unknown key is an error.
Change a profile or a check shows the common changes.
| Key |
Type |
Required |
Meaning |
key |
string matching ^[a-z][a-z0-9-]{0,31}$ |
yes |
The doc type. A spec doc’s frontmatter type, or a map entry in .speccy.yaml, selects the profile with this key. |
name |
string |
yes |
The name the app shows for this doc type, such as Product Requirements Document. |
version |
integer |
|
Speccy sets it on each save. Earlier review runs keep the version they used. |
template |
string |
yes |
The path of the template, relative to the profile file. A doc must have each heading that ends with <!-- required -->, or with <!-- required: app --> at size app and larger (lint.required-headings). |
limits |
object |
|
The size limits that lint checks. A key you leave out keeps its default. |
links |
object |
|
The links a doc of this type must have. |
grounding |
object |
|
The settings of the grounding stage. |
coherence |
object |
|
The settings of the coherence checks. |
verify |
object |
|
The post-build verification gate: the trace IDs it verifies, and the bounds of its repo scan. |
breakdown |
object |
|
The rules Speccy follows when it proposes epics and work items from a Build Ready doc of this type. |
trace |
object |
|
The trace IDs of this doc type. |
waivers |
object |
|
Who approves a waiver, by the level of the check. |
approvals |
object |
|
The approvals that a spec doc of this type needs. |
divergence |
object |
|
The divergence stage: its readers and its build questions. |
lint |
object |
|
The settings of the lint stage. |
checks |
list of object |
yes |
The checks that a review runs besides lint. Each check has a slug, a level and a stage. |
The size limits that lint checks. A key you leave out keeps its default.
| Key |
Type |
Required |
Meaning |
max_words |
integer |
|
The most words in the doc (lint.prose-limit). Default 8000. |
max_section_words |
integer |
|
The most words in one section (lint.prose-limit). Default 900. |
max_sentence_words |
integer |
|
The most words in one sentence (lint.sentence-length). Default 25. |
max_code_block_lines |
integer |
|
The most lines in one code block (lint.asset-nudge). Default 40. |
max_table_rows |
integer |
|
The most rows in one table (lint.asset-nudge). Default 15. |
The links a doc of this type must have.
| Key |
Type |
Required |
Meaning |
upstream |
object |
|
The upstream link that a doc of this type needs (links.has-upstream). |
children |
object |
|
A doc at size min_at or larger must link the bundles it covers (links.has-children). |
The upstream link that a doc of this type needs (links.has-upstream).
| Key |
Type |
Required |
Meaning |
kinds |
list of one of implements, refines, references, supersedes |
yes |
The link kinds that count as an upstream link. |
types |
list of string |
yes |
The profile keys that an upstream doc can have, such as prd. |
required |
boolean |
|
When true, a doc with no upstream link and no standalone acknowledgement fails links.has-upstream. Default false. |
A doc at size min_at or larger must link the bundles it covers (links.has-children).
| Key |
Type |
Required |
Meaning |
kinds |
list of one of implements, refines, references, supersedes |
yes |
The link kinds that count as a link to a covered bundle. |
min |
integer |
|
The fewest links of those kinds that the doc needs. Default 1. |
min_at |
one of feature, app, initiative |
yes |
The smallest doc size that the check applies to. |
The settings of the grounding stage.
| Key |
Type |
Required |
Meaning |
enabled |
boolean |
|
Turns the grounding stage on. It is off by default: a review then makes no claim calls. |
file_contradiction |
one of SHOULD, MUST |
|
The level of grounding.file-contradicts-claim: a claim that a file of the bundle contradicts. The default is SHOULD. |
sources |
object |
|
The source policy: which domains the grounding stage accepts, their tier, their freshness period, and the claim class of a section. |
The source policy: which domains the grounding stage accepts, their tier, their freshness period, and the claim class of a section.
| Key |
Type |
Required |
Meaning |
allow |
list of string matching ^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ |
|
When the list has a host, the grounding stage accepts sources from these hosts only. |
forbid |
list of string matching ^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ |
|
Hosts that Speccy never accepts and never requests. |
domains |
list of object |
|
The tier of each host pattern. A host that matches no pattern is secondary. |
freshness |
object |
|
Days a source of that tier stays usable. Zero is no limit. |
require_primary |
list of string |
|
The claim classes whose sources must all be primary. |
classes |
list of object |
|
Rules that give the claims of a section a claim class, by heading path. The most specific pattern wins. |
unclassified |
one of allow, warn, require-classification |
|
What Speccy does with a claim in a section that matches no class rule. allow does nothing, and warn adds a note to the run. require-classification drops the claim’s sources. Default allow. |
| Key |
Type |
Required |
Meaning |
pattern |
string matching ^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ |
yes |
A host, such as example.com, or *.example.com for its subdomains. |
tier |
one of primary, secondary |
yes |
The tier of a host that matches the pattern. The most specific pattern wins. |
Days a source of that tier stays usable. Zero is no limit.
| Key |
Type |
Required |
Meaning |
primary |
integer |
|
Days a primary source stays usable. |
secondary |
integer |
|
Days a secondary source stays usable. |
| Key |
Type |
Required |
Meaning |
pattern |
string |
yes |
A heading path, with / between headings. A * segment matches one heading, and a trailing ** matches the rest. The match ignores case. |
class |
string |
yes |
The claim class of a section that matches the pattern. The name unclassified is not a valid class. |
The settings of the coherence checks.
| Key |
Type |
Required |
Meaning |
upstream_pending |
one of allow, block |
|
What an approved upstream request does to the verdict of the doc that asks for it. allow: the conflict waits on the linked doc and does not block. block: the conflict still blocks until the linked doc changes. The default is allow. |
The post-build verification gate: the trace IDs it verifies, and the bounds of its repo scan.
| Key |
Type |
Required |
Meaning |
prefixes |
list of string matching ^[A-Z]{2,6}$ |
|
The trace ID prefixes that a verification run checks. Default REQ and NFR. |
exclude |
list of string |
|
Path globs that the repo scan passes over. A list you set replaces the default, which holds vendor/**, node_modules/**, dist/**, build/**, .git/**, **/testdata/**, **/*.min.js, **/*.lock and **/*.sum. |
max_file_kb |
integer |
|
The largest file, in KB, that the repo scan reads. Default 512. |
max_mapper_files |
integer |
|
The most files that the model which finds code targets sees, highest ranked first. Default 200. |
The rules Speccy follows when it proposes epics and work items from a Build Ready doc of this type.
| Key |
Type |
Required |
Meaning |
epic |
string |
|
What one epic is for this doc type. Default: one epic per outcome a user or an operator can see, never a layer of the stack. |
max_trace_ids |
integer |
|
The largest work item, as a count of trace IDs. A larger item gets the SHOULD finding breakdown.size. Default 4. |
order |
list of string |
|
The rules that order the items. A list you set replaces the default: a provider before its consumer, and expand before contract for an interface or a migration. |
The trace IDs of this doc type.
| Key |
Type |
Required |
Meaning |
prefixes |
list of string matching ^[A-Z]{2,6}$ |
|
The trace ID prefixes that this doc type defines. An ID with another prefix gets trace.unknown-prefix. |
cover |
list of string matching ^[A-Z]{2,6}$ |
|
The prefixes of upstream IDs that this doc must cover. Each such ID in an implements target needs a reference or an acknowledgement (trace.coverage). |
Who approves a waiver, by the level of the check.
| Key |
Type |
Required |
Meaning |
should |
one of any_member, non_author, maintainer, forbidden or object |
|
The waiver policy of a SHOULD check. Default non_author. |
must |
one of any_member, non_author, maintainer, forbidden or object |
|
The waiver policy of a MUST check. Default maintainer. |
The approvals that a spec doc of this type needs.
| Key |
Type |
Required |
Meaning |
required |
integer |
|
How many approvals the current version needs. Default 1. |
The divergence stage: its readers and its build questions.
| Key |
Type |
Required |
Meaning |
readers |
integer |
|
How many readers answer the build questions. Default 3. |
questions |
object |
|
How many build questions the stage writes. |
themes |
list of string |
|
The topics that the build questions cover, such as error handling or limits. |
How many build questions the stage writes.
| Key |
Type |
Required |
Meaning |
min |
integer |
|
The fewest build questions. Default 0: the reviewer writes a question only where it sees a real choice. It cannot be larger than max. |
max |
integer |
|
The most build questions. Default 20. |
The settings of the lint stage.
| Key |
Type |
Required |
Meaning |
overrides |
map of object |
|
A level for a lint check, by slug: MUST, SHOULD, INFO, or off. The value off turns the check off. |
slop_extra |
list of string |
|
More filler phrases for lint.slop-phrase to find, on top of its own list. |
acronyms |
list of string matching ^[A-Z][A-Z0-9]{1,5}$ |
|
Acronyms that lint.undefined-acronym accepts with no definition, on top of the common ones. For example the labels of a team’s document kinds: POL, STN, ADR. |
| Key |
Type |
Required |
Meaning |
slug |
string matching ^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+$ |
yes |
The ID of the check: lower-case words with dots between them, such as sdd.data-model. It is unique in the profile. |
level |
one of MUST, SHOULD, INFO |
yes |
The level of a finding. MUST blocks when material: an open MUST finding of an AI stage makes the verdict Not Build Ready only when the judge finds a material gap, where two plausible builder guesses differ in the data model, an interface, security or what the user sees. A deterministic MUST finding always blocks. SHOULD never blocks. |
stage |
one of rubric, grounding, divergence, coherence |
yes |
The review stage that runs the check. |
scope |
one of doc, section |
|
What the check reads. With doc, the check reads the whole doc, or the one section that section names. With section, the check runs on every section, and a waiver covers one section. Default doc. |
question |
string |
|
The question the check asks about the doc. |
pass_when |
string |
|
What must hold for the check to pass. A finding gives it as the fix. |
waiver |
one of any_member, non_author, maintainer, forbidden or object |
|
Who approves a waiver of this check. It replaces waivers.should or waivers.must for this check. |
sizes |
list of one of feature, app, initiative |
|
The doc sizes this check applies to. An empty list applies at every size. |
section |
string |
|
The heading that a rubric check is about, such as Monitoring. The check reads that section with its subsections, and each section of the same doc that it links to by a heading anchor or names by a full heading title of two or more words. An edit to another section does not change its answer, and a waiver of it ends when that section changes. In a doc with no such heading, the check reads the whole doc, and the run notes say so. profile validate warns when no doc of the profile in the folder has the heading. The value none is reserved and names no heading: the check reads the whole doc on purpose, and profile validate and the run notes give no warning about its section. |
reads |
list of one of upstream |
|
The other texts that a rubric check reads besides the doc. With upstream, the check also reads the spec doc of each implements or refines target, such as the PRD, and runs again when that doc changes. Use it for a check that compares the doc with its upstream doc. |