# Changelog

All notable changes to Synth will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [2.4.1] — 2026-07-25

### Fixed

- `scripts/install.sh` now parses the JSON `synth --version` contract
  introduced in 2.4.0, so bootstrap installation certification passes.
- `src/governance/adr-registry.ts` no longer crashes when `docs/adr` is
  absent, which is the case for the published npm package. This allows
  `synth init` and `synth doctor` to succeed after a clean global install.

## [2.4.0] — 2026-07-25

The SYNTH Platform v1.0 Release.

This release marks the stabilization of the SYNTH platform for general adoption.
All remaining v1.0 architecture (kernel, SDK, event model, governance lifecycle,
and replay engine) is frozen and certified.

### Platform v1.0 Certification

- Added the SYNTH Platform v1.0 Manifest at
  `docs/certifications/synth-platform-v1-0-manifest.json`.
- Added `scripts/generate-platform-manifest.js` to regenerate the manifest from
  the current source tree.
- Added `scripts/validate-clean-clone.sh` to verify that the repository builds,
  tests, governs, and certifies from a fresh clone.
- Issued five certification tracks under EXP-PROGRAM-042: Reproducibility,
  Operator Experience, Governance, Architecture Baseline, and Release Readiness.

### Clean-Clone Hardening

- Tracked `docs/generated/` as the committed documentation baseline so that
  `docs:verify-freshness` passes on a clean checkout.
- Removed the undefined `test:first-contact-projection` script from `test:all`.
- Relaxed the `govern-profiler` percentage-sum tolerance for dry-run summaries.
- Excluded volatile `versioning.pullRequest` observations from the discovery
  evidence content hash, making discovery deterministic across clones.

## [2.3.0] — 2026-07-19

The Operator Surface Stabilization Release.

This release completes the stabilization of SYNTH's operator surface before the Incremental Governance program (EXP-PROGRAM-021) begins. Brownfield onboarding, CLI diagnostics, deterministic runtime transitions, and replay recovery are now considered stable foundations.

### Brownfield Bootstrap Hardening

Completed EXP-BROWNFIELD-001, making brownfield onboarding deterministic, mutation-safe, and self-guiding.

- Brownfield Bootstrap Specification in `docs/guides/brownfield-bootstrap-specification.md`.
- Discovery Safety Model with READ_ONLY / PROPOSAL_ONLY / MUTATING command classification.
- Runtime transition contract: Draft → Approved → Committed → Executing → Completed.
- Agent context contract via `.synth/context.json`.
- Namespace-owned CLI help for every command.
- Brownfield Certification test suite in `tests/brownfield-certification.test.js`.

### CLI UX and Diagnostics Hardening

Completed EXP-CLI-001.

- Fixed misleading `govern skipped` diagnostic when `package.json` exists without a `govern` script.
- Eliminated duplicate stdout logging during bootstrap and diagnostics.
- Clarified documentation capabilities vs. generated documentation.
- Removed the `shell: true` deprecation warning from `synth govern`.
- Split `synth doctor` into Runtime Health and Project Health sections.
- Added `synth discover --export` for explicit, immutable discovery baselines.

### Runtime Correctness and Recovery

Completed EXP-RUNTIME-001.

- Mission approval is now atomic: `MISSION_CREATED` and `MISSION_APPROVED` runtime events are emitted before the certified snapshot is persisted.
- Added `synth repair replay` with dry-run and `--approve` modes.
- Repair detects drift between certified Mission snapshots and runtime state and emits compensating events through the `ExecutionGate`.
- Added runtime event-guarantee certification tests in `tests/runtime-repair.test.js`.

### Programs and Process

- Chartered EXP-PROGRAM-021 — Incremental Governance, to transform `npm run govern` into a dependency-aware, fingerprint-based incremental validation system.
- Added ADR-018 — npm Package Publication Through PR and Tag.

## [2.2.0] — 2026-07-18

The First Contact Learning System Release.

### Agent First Contact Learning System

Completed EXP-FIRSTCONTACT-011, turning the First Contact experience into an evidence-driven learning system.

- Canonical `ConversationPattern` artifacts derived from observed first-contact sessions.
- Pattern extraction, validation, promotion, and persistence in `src/first-contact/patterns.ts`.
- `scripts/extract-conversation-patterns.js` to generate patterns from session evidence.
- Quick-start Markdown projections generated from canonical patterns into `docs/first-contact/quick-start/`.
- `scripts/generate-first-contact-quickstart.js` with `--check` drift detection.
- First Contact Experience v2 specification and agent onboarding contract in `docs/first-contact/experience-v2.md`.
- New tests: `tests/first-contact-patterns.test.js`, `tests/first-contact-quickstart.test.js`.

### Governance Cleanup

Marked completed in their charters: EXP-GOV-007, EXP-GOV-008, EXP-GOV-009, EXP-INIT-001, EXP-EXEC-002, EXP-EXEC-003, EXP-EXEC-005.

## [2.1.0] — 2026-07-18

The Runtime Boundary Release. SYNTH now stores governed project runtime data under `.synth/data/` while keeping the source repository independent of `.synth/`.

### Runtime Data Boundary

- Co-located runtime authority and projections under `.synth/data/` for SYNTH-governed projects.
- Added automatic, byte-preserving migration from legacy repo-root `data/` to `.synth/data/`.
- Added `src/infra/paths.ts` as the single source of truth for runtime data paths.
- Added `src/infra/migrate-data-dir.ts` for one-time migration triggered by CLI and verification commands.
- Ungoverned directories — including the SYNTH source repository — continue to use repo-root `data/`.

## [2.0.0] — 2026-07-18

The Governed Execution Release. SYNTH 2.0 is now capable of transforming approved Expeditions into governed repository changes.

### Execution Pipeline

Completed the path from approved Expedition to repository artifact.

- **Execution Intent Model** — introduced explicit execution contracts between planning and runtime; added `ExecutionIntent`, `ExecutionIntentGraph`, and execution lifecycle events.
- **Work Item Runtime** — added deterministic execution dispatch through injected capabilities with lifecycle event emission.
- **Branch-per-Expedition Workflow** — Expeditions now receive isolated repository branches via `VersioningCapability`, recording the base commit in replay.
- **Commit-as-Evidence** — repository revisions are recorded as execution evidence via `EXPEDITION_EXECUTION_COMMITTED` events.
- **Pull Request Projection** — added `ForgeCapability` integration; pull requests are projected execution artifacts recorded via `EXPEDITION_EXECUTION_PROJECTED` events.

### Repository Versioning Capability

Repository operations are now modeled as governed capabilities.

- Generic `VersioningCapability` contract.
- Git reference adapter (`src/environment/git-versioning-provider.ts`).
- GitHub Forge adapter (`src/environment/forge-capability.ts`).
- Repository state observations: branches, commits, remotes, divergence, pull requests.
- Deterministic certification tests for repeatable repository state.

### Governance Maturation

Improved system verification and replay capabilities.

- `synth verify` — executable verification engine with six checks.
- Constitutional layer boundary documentation.
- Projection model documentation.
- Governance Record replay projection.

### Cognitive Continuity

Improved operator recovery and zero-history understanding.

- `synth explain resume` — resume briefing from replayable evidence.
- Interruption benchmark with Repository Authority Index measurement (RAI 0.87 baseline).
- TaskPRO regression journey.

### Runtime Self-Description

Improved runtime transparency.

- Operator briefing (`synth status`).
- Adapter introspection (`synth adapter info`).
- Clean `--json` machine output.
- Runtime integrity checks (`synth doctor`).
- Repository identity detection (`synth explain identity`).

### Internal Milestones

Completed and accepted:

- EXP-PROGRAM-012 — Runtime Self-Description
- EXP-PROGRAM-013 — Cognitive Continuity
- EXP-PROGRAM-014 — Governance Maturation
- EXP-PROGRAM-015 — Repository Versioning Capability
- EXP-PROGRAM-016 — Governed Expedition Execution

All accepted, merged, and passing CI.

## [2.0.0-rc.3] — 2026-07-17

The Era II adoption baseline release: Runtime Self-Description is complete, and the CLI can now be trusted, understood, and resumed by a new reasoning system.

### Added
- EXP-PROGRAM-012 — Runtime Self-Description Program (6 expeditions): Operator Briefing (`synth status`), Extraction Reporting, Adapter Introspection (`synth adapter info`), Clean Machine Output (`--json`), Runtime Integrity (`synth doctor` dist verification), Repository Identity (`synth explain identity`).
- `synth docs generate` returns extraction counts and warns loudly when Markdown files match but zero concepts are extracted.
- `synth adapter info <name>` exposes adapter metadata, state, and health without reading source.
- Global `--json` flag suppresses bootstrap diagnostic logs for machine-clean CLI output.
- `synth doctor` verifies installed `dist/` files against a build-time SHA-256 manifest.
- `synth explain identity` projects repository kind, phase, authority, expected inputs/outputs, and transformation direction from replayable evidence.

### Fixed
- `--json` is now correctly propagated to `synth explain` subcommands.

## [2.0.0-rc.2] — 2026-07-16

The Era I certification release: architecture validation closes, and the first-contact adoption baseline is frozen as historical evidence. Certification-style release notes are published with the GitHub release.

### Added
- EXP-PROGRAM-002 — SYNTH Public Release Program.
- EXP-PROGRAM-010 — Constitutional Hardening Program (7 expeditions): proposal-graph sealing in Mission Studio, signed and certified snapshot artifacts, Genesis intake certification, semantic replay verification, P6 Graph Integrity as a constitutional proof dimension, hardening observability (`synth explain`), permanent regression suites.
- EXP-FIRSTCONTACT-009 — Canonical Journey Re-recording: Archive B (hardened pipeline; 32 events; zero aggregate graph violations under `--strict-graph`; signed snapshot artifact) alongside hash-pinned Archive A (36 violations preserved immutably as forensic evidence); derived Archive A/B comparison projected to docs and website; reproducible recording harness (`record` mode in the shared example runner).
- EXP-PROGRAM-011 / 012 / 013 — Chartered adoption programs: Operator Trust & CLI Integrity, Runtime Self-Description, Cognitive Continuity (dependency-chained).
- EXP-REL-001 — Repository Organization with file naming conventions.
- EXP-REL-002 — Public Documentation (README, Mission Studio Guide, Examples Guide, FAQ).
- EXP-REL-003 — Example Certification (Todo, Blog, CRM, Legacy Node, Polyglot, Monolith).
- EXP-REL-004 — Website (static site under `website/`).
- EXP-REL-005 — Open Source Readiness (LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, templates, release workflow).
- TaskPRO first-contact field experiment evidence annex: independent zero-shot audit (rc.1, Windows, autonomous AI agent) characterizing the trust, discoverability, and continuity gaps that Programs 011–013 answer.

### Fixed
- Mission Studio proposal parent references (identity-space defect producing the 36 graph violations preserved in Archive A).
- Example runner proof `stateHash` (was `undefined`).

## [2.0.0-rc.1] — 2026-07-12

Architecture freeze and certification milestone. This marker represents the v2 kernel freeze and initial public vocabulary baseline, not a published npm package release.

### Added
- Synth v2 freeze.
- Seven public concepts: Mission, Expedition, Evidence, Plan, Event, State, Replay.
- Deterministic execution kernel with replay verification.
- Mission Studio with snapshot lineage.
- Documentation expedition generating seven target docs.
- Operator journey certification.
- Public vocabulary and architecture simplification.
- ADR-001 — Synth v2 Freeze Certification.
- ADR-002 — Product Boundary.
- ADR-003 — Synth v2.1 Validation Program Charter.
- ADR-004 — Synth Eras and Protected Assets.

### Changed
- Repository file naming convention to kebab-case.

## [1.0.0] — 2026-06-29

### Added
- Initial Synth v2 architecture and kernel.
- Event sourcing, replay, and proof generation.