# Changelog

All notable changes to this project 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]

_No changes yet — development continues on `develop`._

## [0.3.0] - 2026-04-21

**Memory-file migration closure** — constitution (#059), roadmap +
tech-stack (#060), roadmap H3 prefix-match fix (#061), and personas
(#062) all now share the same migrator + enricher + validator + umbrella
plumbing. See [RELEASE_NOTES.md](./RELEASE_NOTES.md) for the full
narrative.

### Added

- **Shape migration for `.doit/memory/roadmap.md` and `.doit/memory/tech-stack.md`** (#060)
  - `doit update` (and `doit init`) now detects legacy roadmap/tech-stack files
    missing required H2/H3 sections and inserts placeholder stubs in place,
    preserving all prose byte-for-byte.
  - Roadmap gets `## Active Requirements` with `### P1..P4` when missing.
  - Tech-stack gets `## Tech Stack` with `### Languages/Frameworks/Libraries`
    when missing; patches in only missing subsections when the H2 is present.
  - Both migrations are idempotent and body-preserving (SHA-256 verified).
- New `doit_cli.services._memory_shape.insert_section_if_missing` shared
  helper for section-aware markdown rewriting.

- **Auto-migration of legacy constitution frontmatter** (#059)
  - `doit update` (and `doit init --update`) now detects a
    `.doit/memory/constitution.md` with missing or incomplete YAML
    frontmatter and prepends a placeholder skeleton containing every
    required field from
    [src/doit_cli/schemas/frontmatter.schema.json](src/doit_cli/schemas/frontmatter.schema.json).
  - Existing field values are preserved verbatim; only missing required
    fields are added. Unknown/extra keys are preserved too.
  - Body bytes are preserved byte-for-byte (SHA-256-verified by
    integration tests).
  - Malformed YAML frontmatter surfaces a clear error without modifying
    the file (atomic write).
  - `/doit.constitution` skill gains an enrichment branch that detects
    the new `[PROJECT_*]` sentinels and infers real values by reading
    the body and `doit context show` output — no interactive prompts.
- `doit_cli.utils.atomic_write.write_text_atomic()` helper for crash-
  safe file writes.
- `doit_cli.services._memory_shape.insert_section_if_missing` gains an
  optional `matchers: Mapping[str, Callable[[str], bool]] | None`
  parameter so callers can customise H3 heading-presence detection per
  required title (#061). Default `None` preserves the spec-060
  exact-case-insensitive behaviour; `tech_stack_migrator` is unchanged.
- **Personas.md migration** (#062)
  - New `doit_cli.services.personas_migrator.migrate_personas` — shape
    migrator for `.doit/memory/personas.md` (opt-in: absent file is a
    valid NO_OP, never auto-created). Patches in `## Persona Summary` /
    `## Detailed Profiles` stubs when either required H2 is missing;
    preserves all other prose byte-for-byte. Closes the memory-file
    migration pattern across all four `.doit/memory/*.md` files.
  - New `doit_cli.services.personas_enricher.enrich_personas` — linter
    mode: detects remaining `{placeholder}` tokens, reports `PARTIAL`
    with a sorted, deduplicated `unresolved_fields` tuple, and exits 1
    via the CLI. Never modifies the file; points users at
    `/doit.roadmapit` or `/doit.researchit` for interactive content
    authoring.
  - New `doit memory enrich personas` CLI subcommand (exit 0 / 1 / 2
    matches the `enrich roadmap` / `enrich tech-stack` convention).
  - New `memory_validator._validate_personas` rule: when file present,
    enforces both required H2s and the canonical `### Persona: P-NNN`
    three-digit-zero-padded ID regex; zero issues when file is absent.
  - New contract test locks validator ↔ migrator ID bijection over a
    representative ID corpus; mirrors the spec 061 alignment pattern.

### Changed

- Roadmap migrator now recognises decorated priority H3 headings (#061).
  `### P1 - Critical (Must Have for MVP)`, `### P2 - High Priority
  (Significant Business Value)`, and any other `### P[1-4] <decoration>`
  shape is treated as satisfying the `P1..P4` contract, matching
  `memory_validator._validate_roadmap`'s `^p[1-4]\b` regex semantics.
  `doit memory migrate` on such roadmaps now reports `NO_OP` instead of
  `PATCHED`.
- `doit memory migrate` now reports four rows instead of three — the
  fourth row is personas.md (#062). Order is deterministic:
  constitution → roadmap → tech-stack → personas. The personas.md row
  is emitted even when the file is absent (`action: no_op`), matching
  the opt-in semantic — this is a metadata-only change, not a behaviour
  change for the other three files.

### Fixed

- Roadmap migrator no longer appends duplicate empty `### P1..P4` stubs
  to roadmaps whose priority headings carry suffix decoration (#061 —
  regression introduced in #060 and surfaced by dogfooding against
  doit's own `.doit/memory/roadmap.md`). If an earlier run of the
  buggy migrator added spurious duplicate bare stubs to your
  `roadmap.md`, delete them manually; future `doit update` runs will
  stabilise to `NO_OP`.

- `doit_cli.models.memory_contract.PLACEHOLDER_REGISTRY` and
  `is_placeholder_value()` — authoritative placeholder-detection
  primitives shared by the migrator and the validator.

### Changed

- `ConstitutionFrontmatter.validate()` now classifies placeholder values
  as `WARNING` (not `ERROR`) so a freshly-migrated constitution passes
  `doit verify-memory` immediately.
- `ConstitutionFrontmatter.phase` accepts `int | str` to preserve
  placeholder values through construction; runtime validity is enforced
  in `validate()`.

## [0.2.0] - 2026-04-20

### Added

- **Agent Skills template layout for Claude Code**
  - New `.claude/skills/doit.<name>/SKILL.md` layout generated alongside the
    legacy flat commands by `doit init` and `doit sync-prompts`
  - All 13 workflow commands migrated (`constitution`, `roadmapit`,
    `researchit`, `specit`, `planit`, `taskit`, `implementit`, `reviewit`,
    `testit`, `fixit`, `documentit`, `scaffoldit`, `checkin`)
  - Oversized templates split into `SKILL.md` + supporting reference files
    to stay under the 500-line budget per Anthropic's skill authoring guide
  - `SkillTemplate.validate()` enforces the 500-line and 1,536-char
    combined `description + when_to_use` budgets in CI contract tests
- **Native GitHub Copilot `.prompt.md` frontmatter**
  - `.github/prompts/doit.*.prompt.md` now emit the April 2026 VS Code
    schema: `description`, `agent: agent`, `tools: [...]`, optional `model`
  - `PromptTransformer` maps Claude's `allowed-tools` verbs to VS Code
    tool identifiers (`editFiles`, `search`, `codebase`, `runCommands`,
    `githubRepo`) and rewrites `$ARGUMENTS` to `${input:args}`
  - Contract test `tests/contract/test_copilot_prompt_format.py` fails CI
    if shipped prompts drift from the transformer output — run
    `doit sync-prompts --agent copilot` to resync
- **`DoitError` exception hierarchy**
  - Raise subclasses at boundaries instead of bare exceptions; chain with
    `raise X(...) from e` (ruff B904 enforced)
  - Lives in [src/doit_cli/errors.py](src/doit_cli/errors.py)
- **`ExitCode` constants**
  - Every `typer.Exit(code=…)` uses a symbolic constant from
    [src/doit_cli/exit_codes.py](src/doit_cli/exit_codes.py) — no numeric
    literals
  - Canonical codes: `SUCCESS=0`, `FAILURE=1`, `VALIDATION_ERROR=2`,
    `PROVIDER_ERROR=3`, `AUTH_ERROR=4`, `STATE_ERROR=5`, `USER_CANCEL=130`
- **`format_option()` helper + `OutputFormat` enum**
  - Shared `--format / -f` flag across report-producing commands with
    per-command `allowed` subsets and case-insensitive parsing
  - Lives in [src/doit_cli/cli/output.py](src/doit_cli/cli/output.py)
- **Constitution frontmatter JSON Schema**
  - New canonical schema at
    [src/doit_cli/schemas/frontmatter.schema.json](src/doit_cli/schemas/frontmatter.schema.json)
    defining the YAML frontmatter contract for
    `.doit/memory/constitution.md`
  - Kept in sync with the `platform-docs-site` copy for integration with
    the doit-docs portal
- **`context_loader` service split into a package**
  - Refactored from a single module into a package with one responsibility
    per submodule (loader, merger, cache); public API unchanged
- **GitHub provider branch + issue operations**
  - New branch-creation helpers plus issue-close and issue-comment flows,
    used by `doit.checkin` and the bug-fix workflow
- **mypy enforcement as a pre-commit hook**
  - Type-check errors now block commits; run
    `pre-commit run mypy --hook-stage manual --all-files` locally

### Changed

- `doit sync-prompts` now emits both `.claude/skills/doit.<name>/` and the
  legacy `.claude/commands/doit.<name>.md` files so teams can roll forward
  to the Skills layout at their own pace
- Every `src/doit_cli/**/*.py` starts with `from __future__ import
  annotations`; type hints use `list[X] / X | None` instead of
  `List / Optional`

### Deprecated

- Flat `.claude/commands/doit.<name>.md` templates continue to work in
  this release per Anthropic's back-compat window, but the Skills layout
  is preferred. A future minor release will remove the flat-command
  generator

### Fixed

- Removed unreachable code flagged by ruff in the services layer
- Legacy `github_service` call sites now route through the provider
  abstraction; the standalone service remains only as a shim

## [0.1.17] - 2026-03-26

### Added

- **MCP Server for doit Operations** (#055)
  - Expose doit CLI operations as MCP tools for AI assistant integration
  - Built on official MCP Python SDK with FastMCP
  - Tools: `doit_validate`, `doit_status`, `doit_verify`, and more
  - Zero-config auto-discovery via `.claude/settings.json`

- **Project-Level Personas with Context Injection** (#056)
  - Personas as first-class context source in doit workflow
  - Auto-generates `.doit/memory/personas.md` during roadmap creation
  - Registered in `context.yaml` at priority 3 for automatic injection

- **Persona-Aware User Story Generation** (#057)
  - `/doit.specit` auto-maps user stories to relevant personas
  - Uses P-NNN traceability IDs from persona templates
  - Completes the persona pipeline (specs 053 → 056 → 057)

- **Error Recovery Patterns in All Commands** (#058)
  - Structured `## Error Recovery` sections in all 13 command templates
  - 3-5 documented error scenarios per command with severity indicators
  - Numbered recovery steps, verification commands, and prevention tips

- **Update/Upgrade Flow Improvements**
  - Fixed `doit init --update` to sync all commands to Claude and Copilot

## [0.1.16] - 2026-01-30

### Fixed

- **Windows symlink issue causing empty commands** (#658)
  - Fixed `doit init` not creating Claude/Copilot commands on Windows
  - Root cause: Git on Windows stores symlinks as text files when `core.symlinks=false`
  - Solution: Moved templates into the package (`src/doit_cli/templates/`) eliminating symlink dependency
  - Simplified `get_base_template_path()` to use package-relative paths
  - Package is now fully self-contained and works on all platforms without symlink support
  - `doit init` now correctly creates all 13 command templates on Windows

### Added

- Added `researchit` to `DOIT_COMMANDS` constant for consistency
- Fixed UTF-8 encoding in test files for Windows compatibility

## [0.1.15] - 2026-01-30

### Added

- **Research Command for Product Owners** (#052)
  - New `/doit.researchit` slash command for pre-specification business requirements capture
  - Interactive Q&A workflow: 12 guided questions across 4 phases (Problem, Users, Requirements, Metrics)
  - No technology questions - focused purely on business value and user needs
  - Generates 4 research artifacts:
    - `research.md` - Problem statement, target users, business goals, success metrics
    - `user-stories.md` - User stories in Given/When/Then format with persona references
    - `interview-notes.md` - Stakeholder interview templates with suggested questions
    - `competitive-analysis.md` - Competitor comparison framework
  - Session resume support: Save progress mid-session and continue later
  - Gap-aware feature numbering: Correctly handles directory number gaps
  - Draft cleanup: Automatic removal of draft files after completion
  - Integration with `/doit.specit`: Research artifacts auto-loaded for specification

- **Specit Research Integration**
  - `/doit.specit` now automatically loads research artifacts from prior `/doit.researchit` sessions
  - Seamless handoff from Product Owner research to technical specification

## [0.1.14] - 2026-01-22

### Fixed

- **doit init missing templates** - Fixed `doit init` and `doit init --update` not copying all bundled templates. The following templates were missing:
  - Config files: `hooks.yaml` and `validation-rules.yaml` (only `context.yaml` was copied)
  - Hook templates: `pre-commit.sh`, `pre-push.sh`, `post-commit.sh`, `post-merge.sh` (entire `hooks/` directory was skipped)
  - Workflow document template: `agent-file-template.md`
- Added `copy_hook_templates()` method to TemplateManager for git hook scripts
- Added `copy_workflow_document_templates()` method for workflow document templates
- `doit init` now correctly copies 36 template files (was 28)

## [0.1.13] - 2026-01-22

### Added

- **GitLab Git Provider Support** (#637)
  - Full GitLab REST API v4 implementation (1035 lines)
  - Personal Access Token (PAT) authentication with token validation
  - Issue management: create, read, update, list with label filtering
  - Merge request management: create, read, list with branch filtering
  - Milestone management: create, read, update, list with state filtering
  - Label auto-creation with scoped priority labels (`priority::1` through `priority::4`)
  - Self-hosted GitLab instance support with configurable host
  - Comprehensive error handling (401/403/404/429/5xx)
  - 45 unit tests with 97% requirement coverage
  - Integration test scaffolding for live API testing

- **GitLab Provider Tutorial**
  - Step-by-step guide for GitLab configuration (`docs/tutorials/04-gitlab-provider-tutorial.md`)
  - Personal Access Token creation walkthrough
  - Provider wizard and manual configuration options
  - Self-hosted GitLab setup instructions
  - Troubleshooting guide for common issues

### Changed

- **Documentation Updates**
  - Added Git Provider Configuration section to quickstart.md
  - Updated tutorials index with GitLab provider tutorial
  - Provider comparison table (GitHub, GitLab, Azure DevOps)

## [0.1.12] - 2026-01-22

### Added

- **Git Provider Configuration Wizard** (#636)
  - Interactive `doit provider wizard` command for setting up git providers
  - Auto-detection of provider from git remote URL
  - Support for GitHub, GitLab, and Azure DevOps
  - Token validation against provider APIs
  - `gh` CLI integration for GitHub token retrieval
  - Configuration backup and restore functionality
  - Provider status command: `doit provider status`

- **Constitution and Tech Stack Separation** (#606)
  - Separated `tech-stack.md` from `constitution.md` for cleaner organization
  - `doit constitution cleanup` command for migrating existing projects
  - Context loading optimization with dedicated tech stack source
  - Command overrides support in constitution
  - 24 implementation tasks, 1377 tests pass

## [0.1.11] - 2026-01-22

### Added

- **Unified CLI Package** (#603)
  - Consolidated `doit_cli` and `doit_toolkit_cli` into single unified package
  - Merged 17 files (7 models, 4 utils, 5 services, 1 command) into `doit_cli`
  - Combined two `github_service.py` files into unified service with issue, epic, milestone, and branch operations
  - Cleaner import structure using `doit_cli.*` paths throughout
  - All 1345 tests pass with no test logic modifications

- **Team Collaboration Features** (#602)
  - Git-based sync for constitution and roadmap files across team members
  - Change notifications via watchdog file monitoring
  - Conflict resolution UI for handling merge conflicts
  - Access control with read-only and read-write modes
  - 28 implementation tasks, 18 integration tests

### Fixed

- **Agent Detection** (#596)
  - Improved agent detection before updating instruction files
  - Scripts now correctly detect configured AI agents (Claude, Copilot)
  - Prevents errors when only one agent is configured

### Changed

- **Package Structure**
  - `pyproject.toml` now references only `doit_cli` package
  - Removed `doit_toolkit_cli` directory entirely
  - Import paths standardized across codebase

## [0.1.10] - 2026-01-22

### Added

- **GitHub Milestone Generation from Priorities** (#594)
  - `doit roadmapit sync-milestones` command to create GitHub milestones for priority levels (P1-P4)
  - Automatic assignment of roadmap epics to corresponding priority milestones
  - Detection and prompt to close completed priority milestones
  - `--dry-run` flag to preview milestone sync changes
  - Milestone titles: "P1 - Critical", "P2 - High Priority", "P3 - Medium Priority", "P4 - Low Priority"
  - Seamless integration with GitHub via `gh` CLI

- **GitHub Epic Auto-linking in Spec Creation** (#591)
  - Automatic linking of specs to GitHub epics during `/doit.specit`
  - Fuzzy matching of spec names to roadmap items (80% threshold)
  - Bidirectional linking: spec→epic and epic→spec
  - Interactive epic creation workflow when no epic exists
  - Priority label propagation from roadmap to GitHub issues

- **GitHub Epic and Issue Integration for Roadmap** (#586)
  - Display GitHub epic state (open/closed) in roadmap items
  - `doit roadmapit add` creates GitHub epics with priority labels
  - Smart epic description generation with rationale
  - 30-minute cache for GitHub API responses
  - Custom label support for epics

### Fixed

- **Agent Detection in update-agent-context.sh** (#596)
  - Fixed errors when only one AI agent (Claude or Copilot) is configured
  - Added `detect_configured_agents()` function matching Python's AgentDetector logic
  - Script now only updates instruction files for detected agents
  - Prevents attempts to create/update CLAUDE.md when only Copilot configured (and vice versa)

- **Context Roadmap Summarization** (#593)
  - Fixed roadmap being summarized even when under token limit
  - Summarization now only triggers when roadmap exceeds soft threshold
  - Improved context efficiency and preservation of roadmap details

## [0.1.9] - 2026-01-20

### Added

- **Context Roadmap Summary** (#576)
  - Intelligent roadmap summarization for AI context injection
  - Priority-based summaries: P1/P2 items with full content and rationale, P3/P4 titles only
  - Current feature branch highlighting with `[CURRENT]` marker
  - Completed roadmap items formatted for AI semantic matching
  - Two-tier context condensation: guidance prompt at soft threshold, truncation fallback
  - New `SummarizationConfig` for customizing summarization behavior
  - `doit context show` now displays summarization status (summarized/formatted/complete)

### Changed

- **AI Context Injection**
  - Context loader now uses RoadmapSummarizer for intelligent roadmap condensation
  - Added ContextCondenser for threshold-based condensation with AI guidance prompts
  - Completed roadmap items parsed and formatted for AI semantic understanding

## [0.1.8] - 2026-01-17

### Added

- **Spec-Task Cross References** (#389)
  - `doit xref` command for bidirectional traceability between specs and tasks
  - Coverage reports showing which requirements are implemented
  - Validation rules for orphan tasks and uncovered requirements
  - JSON and line output formats for CI/IDE integration

- **Bug-Fix Workflow** (#440)
  - `/doit.fixit` slash command for structured bug-fix workflow
  - GitHub issue integration for bug tracking
  - AI-assisted investigation and root cause analysis
  - Fix planning with test scenarios
  - Reuses existing reviewit/testit commands

- **Automatic Mermaid Diagram Generation** (#472)
  - `doit diagram` command for auto-generating diagrams from specs
  - User journey flowcharts from user stories
  - Entity relationship diagrams from data models
  - Architecture diagrams from component descriptions
  - Syntax validation before insertion
  - Preview mode and strict validation options

### Changed

- **Documentation Updates**
  - Updated README.md, quickstart.md, tutorials with new commands
  - Added `/doit.fixit` to all command reference tables
  - Added `doit validate`, `doit status`, `doit xref`, `doit diagram` CLI commands
  - Fixed 2 broken documentation links
  - Audited and verified all 43 documentation files

- **Roadmap Milestone**
  - All P1 and P2 items completed - MVP achieved
  - 13 total items shipped (4 P1, 8 P2)

## [0.1.7] - 2026-01-16

### Fixed

- **Pre-push hook fails with extra arguments** (#374) - Fixed pre-push and pre-commit hook templates incorrectly passing `"$@"` to `doit hooks validate`, which only expects a single `hook_type` argument. Git passes remote name and URL as CLI arguments to pre-push hooks, causing validation to fail with "Got unexpected extra arguments".

## [0.1.6] - 2026-01-15

### Fixed

- **sync-prompts command not finding templates** - Fixed `doit sync-prompts` failing with "command not found in templates folder" when used in end-user projects. The command now correctly falls back to bundled package templates when project templates don't exist.

## [0.1.5] - 2026-01-15

### Changed

- **Unified Template Management** (#171)
  - Single source of truth: All doit command templates now live in `templates/commands/`
  - Copilot prompts are generated dynamically via transformation during `doit init`
  - Removed duplicate `templates/prompts/` directory (11 files)
  - Maintainers edit one file; changes apply to both Claude Code and GitHub Copilot

### Added

- **GitHub Copilot Prompts Synchronization** (#023)
  - `doit sync-prompts` command to generate Copilot prompt files from command templates
  - `doit sync-prompts --check` to detect drift between templates and prompts
  - Automatic YAML frontmatter stripping and $ARGUMENTS placeholder handling
  - Selective synchronization support for individual commands

- **Git Hooks Workflow Enforcement** (#025)
  - `doit hooks install` and `doit hooks uninstall` commands for managing Git hooks
  - Pre-commit hook validates feature branches have spec.md
  - Pre-push hook validates required artifacts (spec.md, plan.md, tasks.md)
  - Configurable via `.doit/config/hooks.yaml`
  - Bypass with `--no-verify` for emergency fixes

- **AI Context Injection** (#026)
  - Automatic loading of constitution.md and roadmap.md for all commands
  - `doit context show` command to display loaded context
  - `doit context status` command to show configuration and file availability
  - Feature branch detection loads current spec automatically
  - Related spec discovery based on keyword matching
  - Configurable via `.doit/config/context.yaml`

- **Template Context Injection** (#027)
  - All 11 doit command templates now include context loading step
  - AI assistants automatically receive project context before executing commands
  - Context loading positioned before main logic in all templates
  - Graceful handling of missing context files

- **Documentation and Tutorial Refresh** (#028)
  - Updated quickstart.md with CLI commands table and context injection documentation
  - Updated README.md with separate CLI and slash command sections
  - Regenerated feature index with all 19+ features
  - Added workflow enforcement documentation
  - Updated tutorials with context injection and sync-prompts mentions

- `Agent.needs_transformation` property for determining which agents require template transformation
- `TemplateManager._transform_and_write_templates()` for on-demand prompt generation
- 15 integration tests for context injection
- 29 new unit tests for unified template functionality

## [0.1.4] - 2026-01-13

### Fixed

- **GitHub Copilot prompt files**: Replaced deprecated `mode: agent` with `agent: true` (#139)
  - Updated all 11 prompt files in `/templates/prompts/`
  - Ensures compatibility with VS Code 1.106+ and current GitHub Copilot specification
  - Eliminates deprecation warnings when using Do-It prompts

### Added

- **Constitution command improvements** (#131)
  - Dotfile exclusion: Excludes dotfiles and dotfolders when scanning for context
  - Greenfield detection: Detects empty/new projects and provides interactive questioning

- **Comprehensive tutorials** (#111, #112, #113)
  - Added Do-It workflow tutorials with step-by-step guides
  - Updated quickstart and upgrade guides with correct commands

## [0.1.3] - 2026-01-13

### Added

- Implemented Gitflow-inspired branching strategy with `develop` as default branch (#75)
  - `develop` is now the default branch for feature integration
  - `main` reserved for production-ready releases
  - Updated CONTRIBUTING.md with new branching workflow
  - Added release process documentation for maintainers

### Fixed

- Roadmap templates now contain placeholder syntax instead of sample data (#56)
  - `templates/memory/roadmap.md` - clean template for new projects
  - `templates/memory/roadmap_completed.md` - clean template for tracking completed items
