# Changelog — @cleepi/sdd

All notable changes to this package are documented here.

Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/).
Versioning: [SemVer](https://semver.org/spec/v2.0.0.html). Pre-`1.0.0`, minor
bumps may include breaking changes.

## [Unreleased]

## [0.2.0] — 2026-05-27

**BREAKING.** Substantial redesign of the SDD workflow per
[cleepi spec 0005](../../docs/specs/0005-sdd-redesign.md). New
artifact ontology, new folder layout, new slash commands. Migration
steps below.

### Added

- **Journal** as a new artifact type. Per-ticket
  (`docs/<ticket-id>-slug/journal.md`), append-only log of in-flight
  thinking — dead ends, blockers, surprises. Stack-pointer-plus-log
  shape: `## Current state` overwritten each session, `## Log`
  append-only.
- **Constitution** as a new optional artifact type. `CONSTITUTION.md`
  at repo or package root, for projects with real invariants worth
  codifying. Invariants only — code rules live in `AGENTS.md`,
  process rules live in the sdd skill, one-off design choices live
  in spec Decision sections.
- `/journal <text>` slash command. Appends entry to current
  ticket's journal; overwrites Current state.
- `templates/journal.md` — stack-pointer-plus-log skeleton with
  inline discipline guidance.
- `templates/constitution.md` — invariants-only skeleton with
  anti-examples (what does NOT belong here).
- **Voice and length discipline** in the skill: principles, six
  anti-patterns, the delete test, length cues per artifact. Long
  artifacts when short would do are now a defect, not a preference.
- **Discriminator test** in the skill: "what happens if violated?"
  routes content to the right artifact (CONSTITUTION / AGENTS.md /
  spec Decision section / sdd skill).
- **Ticket-keyed folder layout** (`docs/AC-NNN-slug/`,
  `docs/LIN-NNN-slug/`, `docs/DRAFT-NNN-slug/`, etc.). Folder name
  is the cross-link to the tracker; no `jira:` frontmatter to
  forget. Generic format — tracker prefix is unvalidated.
- Spec frontmatter gains optional `ticket:` and `ticket-url:`
  fields.
- Required `## Decision` section in specs (Alternatives considered
  / Rationale / Consequences). Required before flipping to
  `accepted`.

### Changed

- **Spec body structure.** From 8 fixed sections to 3 required
  (What / Why / Decision) + 5 opt-in (Concrete surface / Phased
  rollout / Open questions / Non-goals / Risks). Optional sections
  appear only when they add information — the delete test enforces
  this.
- **Spec section names.** `Problem` → `What` (works for features,
  not just bug-fix framing). `Why now` collapses into `Why`.
- **`/spec` prompt** now asks for a ticket ID interactively;
  defaults to `DRAFT-NNN` if no tracker exists.
- **`/changelog` prompt** updated: spec link format is now
  `[spec AC-NNN](docs/AC-NNN-slug/spec.md)`. No more ADR-link
  suggestion.
- **`packages/sdd/SPEC.md`** rewritten to the purpose-and-scope
  shape the new skill describes (was structured as a feature spec).
- **`packages/sdd/README.md`** rewritten for v0.2.0 conventions.

### Removed

- **ADR as a separate artifact type.** Decision rationale moves to
  the required spec `## Decision` section. Durable rules move to
  the optional `CONSTITUTION.md`.
- `/adr` slash command.
- `templates/adr.md`.
- `prompts/adr.md`.

### Migration from v0.1.x

Breaking change. Full guide in [README “Migration from v0.1.x”](./README.md#migration-from-v01x). Summary:

1. Move existing ADR content into the relevant spec's
   `## Decision` section. Mark old ADRs `superseded by spec <id>`
   (preserve bodies).
2. Old `docs/specs/NNNN-*.md` and `docs/adr/NNNN-*.md` files don't
   have to move. New work uses ticket-keyed folders
   (`docs/<ticket-id>-slug/`).
3. Start writing journals for active work. Skip retroactive
   journals for already-shipped specs.
4. Add `CONSTITUTION.md` *only if* your project has real invariants.
   Most don't need one.

No automated migration tooling — intentional, unhurried transition.

## [0.1.0] — 2026-05-24

### Added
- Initial package scaffold.
- `skills/sdd/SKILL.md` teaching the SDD workflow (spec, ADR, changelog
  conventions; scope resolution; numbering; status transitions; bootstrap
  exception).
- Slash command prompts: `/spec`, `/adr`, `/changelog`.
- File templates under `templates/`: `spec.md`, `adr.md`,
  `changelog-section.md`.
- README documenting conventions for human readers.
- [SPEC.md](./SPEC.md) — package purpose, scope, non-goals.
- [ADR 0001](./docs/adr/0001-template-format-madr-lite.md) — chose MADR-lite
  with YAML frontmatter for spec and ADR templates.

[Unreleased]: https://github.com/cleevio/cleepi/compare/sdd-v0.2.0...HEAD
[0.2.0]: https://github.com/cleevio/cleepi/releases/tag/sdd-v0.2.0
[0.1.0]: https://github.com/cleevio/cleepi/releases/tag/sdd-v0.1.0