docs: update changelog and readme

Author: benym

CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to @rpamis/comet will be documented in this file.
 
+## What's Changed [0.2.6] - 2026-05-23
+
+### Added
+
+- **Build decision enforcement**: Build guard and `comet-state.sh transition build-complete` now require `isolation` and `build_mode` before moving from build to verify
+- **Direct mode override**: Full workflows must set `direct_override: true` before using `build_mode: direct`; hotfix/tweak remain allowed by default
+- **Configurable guard commands**: Guard scripts now read `build_command` and `verify_command` from the change `.comet.yaml` or repo-root Comet config before falling back to auto-detected build commands
+- **Archive diff preview**: Archive sync prints a unified diff before overwriting an existing main spec when it differs from the delta spec
+- **Cross-platform script smoke CI**: Added Ubuntu, macOS, and Windows smoke coverage for Comet shell scripts and portable shell tests
+- **Shell line-ending policy**: Added `.gitattributes` rules to keep shell and Bats scripts on LF endings
+
+### Changed
+
+- **Guard failure output**: Guard checks now preserve and print command failure output, plus actionable `Next:` hints for missing build decisions and unfinished tasks
+- **Command handling**: Project commands run through `bash -lc`, Maven uses `mvnw` or `mvn.cmd` where appropriate, and Windows Git Bash paths are handled in shell test helpers
+- **Archive step counting**: Dry-run, delta sync, annotation, move, and archive status steps now count real executed steps without double-counting repeated operations
+- **English docs and skills**: Synced the English README and Comet skill text with the Chinese build-decision, command-config, and archive behavior descriptions
+
+### Fixed
+
+- **Configured command persistence**: `comet-state.sh set` now escapes sed replacement metacharacters so command values containing `&`, `|`, or backslashes are preserved
+- **Optional schema fields**: YAML validation now recognizes `direct_override`, `build_command`, and `verify_command`
+- **Quoted YAML values**: State, guard, and validator scripts now strip only wrapping quotes instead of deleting all quote characters from values
+
+### Tests
+
+- Added coverage for missing build decisions, direct-mode override blocking and allowance, configured build/verify commands, command metacharacter preservation, unfinished-task remediation output, archive step counts, and cross-platform path handling
+
 ## What's Changed [0.2.5] - 2026-05-22
 
 ### Added

README.md

@@ -263,7 +263,6 @@ Comet ensures agent execution reliability through automated state transitions:
    - `isolation` must be `branch` or `worktree`
    - `build_mode` must be selected before leaving build
    - Full workflow `build_mode: direct` requires `direct_override: true`
-   - Guard failures include `Next:` remediation hints so agents know which user decision or command is required
 
 5. **Verification Evidence** — Guard enforces proof before phase advance
    - `verify-pass` transition requires `verification_report` pointing to an existing report file
@@ -273,7 +272,6 @@ Comet ensures agent execution reliability through automated state transitions:
 
 6. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
    - Validates entry state, syncs delta specs to main specs
-   - Prints a diff before overwriting an existing main spec when it differs from the delta spec
    - Annotates design doc and plan frontmatter
    - Moves change to archive directory and updates `archived: true`
    - Supports `--dry-run` for preview

assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.5",
+  "version": "0.2.6",
   "skills": [
     "comet/SKILL.md",
     "comet/scripts/comet-guard.sh",

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpamis/comet",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "OpenSpec + Superpowers dual-star development workflow",
   "keywords": [
     "comet",