v2.0.0 — scope cut and state consolidation

Changelog

All notable changes to software-engineer-agent are documented here.
This project follows Keep a Changelog and
Semantic Versioning.

[2.0.0] — 2026-04-15

v2.0.0 is a disciplined scope cut and state-model consolidation driven
by the refactor documented in
docs/specs/2026-04-15-scope-and-state-refactor.md. It removes five
user-facing commands and two agents whose methodology is better served
by composition with external plugins, and bumps the project state
schema from 1 to 2 with automatic one-way migration.

Removed (BREAKING)

• Commands: /sea-ship, /sea-review, /sea-debug, /sea-milestone,
  /sea-undo. Command surface narrowed from 11 to 6.
• Agents: reviewer (Sonnet) and debugger (Haiku). Agent surface
  narrowed from 6 to 4 (plus _common.md, the shared operating
  constitution). Both had no callers after the commands above were
  deleted.

Changed (BREAKING)

• State schema bumped from 1 to 2. scripts/state-update.sh now
  auto-migrates schema_version: 1 → 2 on first touch. The bump is
  the contract that the project uses the two-file auto-QA marker scheme
  described below. Migration is one-way and idempotent; there is no
  rollback in the script. The pre-scope-cut git tag is the floor.
• Auto-QA marker split into two files. The .sea/.needs-verify
  marker is now existence-only — the hook ignores its content.
  A new sibling file .sea/.verify-attempts holds the retry counter
  as {"attempts": N}, written atomically via jq to a mktemp file,
  then mv-ed into place. hooks/auto-qa clears both files on every
  terminal state (pass, loop-protection give-up, hard give-up,
  host-compat fail, missing test runner). A v1 backward-compatibility
  fallback reads the marker's legacy integer content when
  .verify-attempts is absent, so migrated v1 projects keep working
  through the rollover.

Changed

• /sea-roadmap absorbs /sea-milestone. A new "Adding a milestone
  to a completed project" section in skills/sea-roadmap/SKILL.md
  documents the clarify-questions + planner Mode A + milestone boundary
  marker + current_milestone state field flow. Plain /sea-roadmap add "<description>" still covers single-phase appends; the milestone
  flow triggers when the description spans multiple phases or the user
  explicitly names a new milestone.
• /sea-go delegates review and debug to composition. Step 5
  (blocked executor) now recommends obra/superpowers:debugging or
  addyosmani/agent-skills:debugging if installed. Step 6.5 (previously
  the internal reviewer call) now notes the availability of
  addyosmani/agent-skills:code-review if installed instead of
  invoking a SEA-owned reviewer.
• Auto-QA retry constants. hooks/auto-qa now exports
  MAX_RETRIES=2 and TEST_TAIL_LINES=30 as named constants at the
  top of the file with rationale comments. Block-decision messages
  reference the constant so raising the retry budget in one place
  updates every user-visible message.
• Agent maxTurns rationale. Every surviving agent
  (executor 30, planner 20, researcher 15, verifier 12) now has
  a YAML-comment rationale explaining the cap and how to tune it.

Added

• docs/STATE.md v2.0.0 audit with per-file writer/reader/missing/
  corrupted details, cross-file invariants (now nine, including a new
  invariant pairing .needs-verify and .verify-attempts), and a
  "what if state.json and roadmap.md disagree?" decision matrix. The
  v1.0.0 reference is preserved verbatim as a historical subsection.
• docs/specs/2026-04-15-scope-and-state-refactor.md — the spec that
  drove this release.
• docs/specs/2026-04-15-scope-and-state-refactor-journal.md —
  phase-by-phase journal of the refactor execution.
• docs/migration/v1-to-v2.md — migration guide for anyone on v1.x.
• CHANGELOG.md — this file.
• evals/suites/state/v1-to-v2-migration.sh — verifies the schema
  migration is correct and idempotent.
• evals/suites/hooks/auto-qa-two-file-full-cycle.sh — regression
  for the two-file marker scheme's retry-then-give-up cycle.
• evals/fixtures/states/v1-legacy.json — legacy v1 state fixture for
  the migration eval. The four shared state fixtures
  (fresh/executing/blocked/planning) were bumped to schema_version: 2.
• Migration from v1.x section in README.md mapping each deleted
  command to its composition replacement.

Fixed

• Documentation drift between README.md, DESIGN.md, and the
  filesystem (phantom counts, [NAME] placeholder, Draft status).
• Overloaded .sea/.needs-verify marker that encoded both "verify
  needed" and "retries so far" in the same file.
• Missing rationale for maxTurns: 30 and the loop-protection
  threshold 2 in hooks/auto-qa.

Migration

See docs/migration/v1-to-v2.md for the
full migration path — composition replacements for every deleted
command, how the state schema auto-migration works, how to verify it,
and how to recover if something goes wrong.

Notes

• plugin.json version bumped from 1.0.0 → 2.0.0.
• The pre-scope-cut git tag marks the pre-v2.0.0 main HEAD and is
  the only rollback floor. State schema migrations are one-way:
  reverting the code does not roll back a migrated .sea/state.json
  in a user project.