Docs

SpecDD Framework Changelog

[1.5] - 2026-07-16

Clarified spec-edit authority: a .sdd file selected by the request, an active SpecDD workflow, or an authorized task is modifiable without an Owns or Can modify entry, while nearby, inherited, and referenced specs remain unselected.
Added bootstrap control-file rules: agents treat the installed .specdd/bootstrap.md as immutable and edit project or local overrides only when explicitly authorized.
Added a Relevance Gate requiring added or materially edited entries to affect authority, behavior, boundaries, necessary context, or verification, without turning scoped work into cleanup of untouched legacy entries.
Added intended-path resolution for new targets and pre-operation authority snapshots for non-.sdd project artifacts, preventing spec edits from silently widening the same operation unless the authority change and corresponding artifact change were explicitly requested together.

Reworked non-spec write authority so Owns defines exclusive authoritative ownership with implicit read and edit permission, while Can modify grants only additional non-owning permission and never overrides the owning spec.
Changed path-based context semantics so References and Depends on path entries imply read access only, and Can read is reserved for additional context not already available through inheritance or another section.
Tightened spec authoring around one canonical section and polarity per statement, independent Must not rules, exact paths over unnecessary globs, and narrow authority patterns that remain valid for every current and future match.
Changed inline notation so code symbols and externally meaningful code contracts use @ references consistently, inline code marks exact literal or code-formatted text, and paths inside inline code remain literal and non-resolving.
Changed conflict handling so stricter compatible constraints may narrow each other, while required-versus-forbidden behavior and competing ownership claims are reported as unresolved conflicts.
Updated the compliance checklist and examples to demonstrate the new ownership, relevance, glob, symbol, literal, and conflict rules; the comprehensive example is explicitly not a template.

Added stronger guidance that specs describe durable subjects and outcomes, not tickets, prompts, migration notes, adoption plans, or task contracts.
Added rules to keep negative requirements local and plausible, avoiding unrelated Must not lists and obvious non-goals.
Added directory-spec guidance: directory specs describe local structure and immediate child roles, while substantial child behavior belongs in nearer same-basename specs.
Added root spec naming rules: the root .sdd file must live at the selected content root and match that root directory basename.
Added directory-level spec resolution, including parent-held and local directory specs, case-insensitive basename matching, and ambiguity handling.
Added an agent-facing .sdd syntax checklist for section labels, inline values, indentation, task markers, explicit paths, key-value lines, and comments.
Added guidance for symbol references, inline code spans, explicit path preferences, and content-root path usage.
Added tool context discovery rules for exact path resolution, directory links, recursive glob expansion, deduplication, and context inclusion reasons.

Changed references language from “horizontal references” to explicit context references that may point anywhere resolvable by explicit path or symbol.
Changed Purpose, Must, Must not, Forbids, Tasks, Platform, Structure, References, and Exposes descriptions to emphasize outcomes, boundaries, dependency direction, and subject ownership.
Changed recommended section order so Done when appears before Scenario and Example.
Changed task guidance from implementation-only wording to broader work/change wording.
Changed malformed glob guidance: malformed glob patterns are valid text, not .sdd syntax errors.
Changed examples from billing/invoice examples to the Travel Planner/Itinerary example set consistently across the bootstrap.
Changed common spec role guidance to remove app.sdd as the root default and add workflow, operation, interface, dataset, schema, and runbook examples.

Clarified that References are read context only and never grant write authority.
Clarified that parent/facade Exposes entries may include child-owned surfaces only when the parent deliberately presents, routes, aggregates, or proxies that surface.
Clarified that broad prohibitions belong in the nearest shared parent or policy spec instead of being repeated in every child.
Clarified compactness rules to discourage duplicate inverted requirements, task-shaped Purpose or Must entries, far-field exclusions, deep inventory in parent specs, and platform labels mixed with subject roles.

Formalize the SpecDD language rules in the bootstrap, making .sdd syntax, section bodies, continuation lines, tasks, comments, inline code, paths, and @ references explicit.

Improve agent bootstrap instructions for resolving relevant specs before editing.
Strengthen write authority guidance so agents better distinguish context from permission to modify files.
Expand minimal and complete spec examples to make valid SpecDD usage easier to infer.
Improve internal benchmark performance on the two higher-signal cases covering ambiguous authority and a larger workflow: combined Codex plus Claude score increased from 86.36% to 90.91%, and Claude Sonnet score increased from 85.71% to 94.81%.

Add a more structured embedded agent contract while preserving the Markdown bootstrap format.
Add rationale notes for important rules so agents can handle edge cases and competing instructions more reliably.

Clarify same-directory basename matching, directory-based inheritance, and explicit horizontal references.

Initial experimental release.