# 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.3.2] — 2026-06-02

The SDD cockpit — a TUI extension that makes the workflow drivable
from inside pi. See
[spec DRAFT-001](./docs/DRAFT-001-spec-review-tui/spec.md).

v0.3.0 and v0.3.1 were never tagged; this release rolls all three
phased increments into one. Patch bumps were used for the sub-phases
because the sdd package reserves minor bumps for breaking changes
pre-1.0; the changes here are additive.

### Added

- **Extensions** as a fourth ship target of `@cleepi/sdd`, alongside
  skills, prompts, and templates. The package now ships executable
  TUI code in `extensions/`. See updated
  [SPEC.md](./SPEC.md).
- **Spec cockpit** — a TUI extension installed automatically when
  `@cleepi/sdd` is loaded:
  - **Awareness widget** below the editor (`📄 <path> · N edits`)
    shows which spec the agent most recently touched and how many
    `.md` files it has edited this session.
  - **`/specs` slash command** and **`alt+s` keybinding** open the
    review pane (right-anchored, full terminal height).
  - **View mode** renders markdown in the pane; **diff mode** (`d`)
    shows a unified diff vs. the session-start snapshot; **select
    mode** (`v`) highlights a line range and **`enter` quotes it
    into the chat editor** as a markdown block with a
    machine-readable reference line (`sdd:<path>#L<start>-L<end>`).
  - **Package-keyed tree** with status badges from frontmatter
    (`○ draft`, `● accepted`, `◐ shipped`, `× superseded`).
  - **Filters**: `/` for text (substring on relative path),
    `1`–`4` for status, `e` for files edited this session. All
    stackable; `esc` clears.
  - **`s` flip status** with inline confirm + auto-stamps
    `accepted:` / `shipped:` dates.
  - **`J` journal append** and **`C` changelog append** —
    structured edits with diff preview before write. Both read
    from `templates/*.md` (templates remain the shared contract
    between slash-command prompts and extension actions).
  - **`pi.peerDependencies`** declares `@earendil-works/pi-coding-agent`.

### Changed

- `packages/sdd/SPEC.md` now lists Extensions alongside Skill,
  Prompts, and Templates as the four things this package ships.
- `skills/sdd/SKILL.md` Quick reference table mentions `/specs`
  and the cockpit verbs.

## [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