Configuration: spec-sync docs

Reference

SpecSync 5.0 separates canonical validation settings from the verified SDD policy:

.specsync/config.toml configures specs, source discovery, rules, maturity guards, and integrations.
.specsync/sdd.json enables and protects the change lifecycle, meaningful paths, verification commands, and custom artifacts.

Neither file accepts provider credentials or model commands.

Initialize

specsync init

New projects receive the current layout. Existing projects can migrate configuration with specsync migrate and explicitly enable the 5.0 lifecycle with specsync change adopt.

Configuration resolution is:

.specsync/config.toml
.specsync/config.json      legacy fallback
.specsync.toml             legacy fallback
specsync.json              legacy fallback
defaults

Canonical TOML

specs_dir = "specs"
source_dirs = ["src"]
schema_dir = "db/migrations"
schema_pattern = "CREATE (?:VIRTUAL )?TABLE(?:\\s+IF NOT EXISTS)?\\s+(\\w+)"
exclude_dirs = ["__tests__"]
exclude_patterns = ["**/__tests__/**", "**/*.test.ts"]
source_extensions = ["rs", "ts"]
required_sections = ["Purpose", "Public API", "Invariants", "Behavioral Examples", "Error Cases", "Dependencies", "Change Log"]
export_level = "member"
parse_mode = "ast"
enforcement = "strict"
task_archive_days = 30

[rules]
max_changelog_entries = 20
require_behavioral_examples = true
min_invariants = 1
max_spec_size_kb = 50
require_depends_on = false

[github]
repo = "owner/repo"
drift_labels = ["spec-drift"]
verify_issues = true

[companions]
design = true

All keys use snake_case. specsync migrate preserves explicit empty arrays and refuses lossy conversion when legacy custom rules cannot be represented safely.

Core options

Option	Type	Default	Purpose
`specs_dir`	string	`"specs"`	Recursive canonical spec directory
`source_dirs`	string[]	auto-detected or `src`	Source roots used for coverage and generation
`schema_dir`	string	unset	SQL migration directory
`schema_pattern`	string	built-in CREATE TABLE pattern	Table-name capture regex
`required_sections`	string[]	seven contract sections	Required `##` headings
`exclude_dirs`	string[]	common test directories	Directory exclusions
`exclude_patterns`	string[]	common test globs	Additive source exclusions
`source_extensions`	string[]	all supported	Restrict source discovery
`export_level`	`member` or `type`	`member`	Public-symbol validation depth
`parse_mode`	`regex` or `ast`	`regex`	Extraction strategy where AST support exists
`enforcement`	`warn`, `enforce-new`, or `strict`	`warn`	Default failure policy
`task_archive_days`	integer	unset	Age threshold used by task archival

Validation rules

The [rules] table controls spec-quality constraints:

Key	Purpose
`max_changelog_entries`	Warn when a Change Log needs compaction
`require_behavioral_examples`	Require a populated Behavioral Examples section
`min_invariants`	Set the minimum invariant count
`max_spec_size_kb`	Warn on oversized specs
`require_depends_on`	Require explicit dependencies

Maturity lifecycle guards

Module maturity (draft, review, active, stable, deprecated, archived) is separate from the SDD delivery lifecycle. Configure allowed states, age guidance, and transition guards in TOML:

[lifecycle]
track_history = true
allowed_statuses = ["draft", "review", "active", "stable", "deprecated", "archived"]

[lifecycle.max_age]
draft = 30
review = 14

[lifecycle.guards."review->active"]
min_score = 80
require_sections = ["Behavioral Examples", "Error Cases"]
no_stale = true
stale_threshold = 5
message = "Resolve drift before activation"

Use specsync lifecycle, specsync stale, and specsync score to inspect these policies. They do not replace the verified SDD states described below.

Verified SDD policy

.specsync/sdd.json is versioned independently so upgrading cannot silently introduce new CI gates:

{
  "version": 1,
  "enabled": true,
  "require_change_for_meaningful_files": true,
  "meaningful_paths": ["src/", "tests/", "site/", ".github/", "Cargo.toml"],
  "ignored_paths": [".specsync/", "specs/"],
  "verification_commands": ["fledge run test"],
  "custom_artifacts": {},
  "principles_file": null
}

Verification commands are parsed as explicit argument lists and run without a shell. Pipes, substitutions, redirections, and other shell operators are rejected. Committed policy/configuration files remain meaningful even if a broad ignored path would otherwise cover them.

custom_artifacts maps an artifact name to a project-owned Markdown template. principles_file optionally adds project governance to interviews and agent context.

Custom modules

Override automatic source ownership when a module spans unusual paths:

[modules."auth"]
files = ["src/auth/service.ts", "src/auth/middleware.ts"]
depends_on = ["database"]

[modules."api"]
files = ["src/routes/"]
depends_on = ["auth", "database"]

GitHub integration

[github]
repo = "CorvidLabs/spec-sync"
drift_labels = ["spec-drift", "needs-update"]
verify_issues = true

The repository is auto-detected from Git when repo is omitted.

Agent-native enrichment

specsync generate is deterministic and local. Use specsync agents install or specsync mcp to let an existing coding agent enrich artifacts under that agent's own credentials and permissions. Legacy AI configuration keys are ignored with migration guidance; their values are never printed or executed.

See AI and coding agents and the workflow guide for the surrounding lifecycle.