universal-dev-standards 5.0.0-rc.8 → 5.0.0

package/bundled/core/branch-completion.md

@@ -0,0 +1,158 @@
+# Branch Completion Workflow
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/branch-completion.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-03-20
+**Applicability**: All projects using Git branching workflows
+**Scope**: universal
+**Inspired by**: [Superpowers](https://github.com/obra/superpowers) — finishing-a-development-branch (MIT)
+
+---
+
+## Purpose
+
+Define a standardized workflow for completing development branches, including prerequisite checks, four completion options, and safe discard procedures. This standard prevents premature merges, forgotten branches, and accidental data loss.
+
+定義分支完成的標準化工作流，包含前置檢查、四個完成選項與安全丟棄流程。防止過早合併、遺忘分支與意外資料遺失。
+
+---
+
+## Glossary
+
+| Term | Definition |
+|------|-----------|
+| Branch Completion | The process of finishing work on a feature/fix branch |
+| Prerequisites | Conditions that must be met before a branch can be considered complete |
+| Discard Confirmation | A safety mechanism requiring explicit input before deleting work |
+
+---
+
+## Core Principle — Test Before Talk
+
+> **All tests must pass before any completion option is considered.**
+
+所有測試必須通過，才能討論完成選項。
+
+---
+
+## Prerequisites
+
+Before a branch can be completed, ALL of the following must pass:
+
+| Check | Command (example) | Required |
+|-------|-------------------|----------|
+| All tests pass | `pnpm test` | Yes |
+| Lint passes | `pnpm lint` | Yes |
+| Type check passes | `pnpm tsc --noEmit` | Yes |
+| No uncommitted changes | `git status --porcelain` | Yes |
+
+If any prerequisite fails, the branch is **not ready for completion**. Fix the issues first.
+
+---
+
+## Four Completion Options
+
+### Option 1: Merge Locally（本地合併）
+
+Merge the branch into the target branch on your local machine.
+
+```bash
+git checkout main
+git merge --no-ff feature/my-feature
+git branch -d feature/my-feature
+# If worktree exists:
+git worktree remove .worktrees/my-feature
+```
+
+**When to use**: Small changes, solo work, no review needed.
+
+### Option 2: Create Pull Request（建立 PR）
+
+Push the branch and create a pull request for review.
+
+```bash
+git push -u origin feature/my-feature
+gh pr create --title "feat: add my feature" --body "..."
+```
+
+**When to use**: Team projects, changes needing review, CI/CD pipelines.
+
+### Option 3: Keep As-Is（保持現狀）
+
+Keep the branch without merging or creating a PR.
+
+- Record the branch state and reason for deferral
+- Set a reminder to revisit
+
+**When to use**: Work in progress, waiting for dependencies, exploring alternatives.
+
+### Option 4: Discard（丟棄）
+
+Delete the branch and all its changes.
+
+**Safety requirement**: The user must **explicitly confirm** by typing the branch name.
+
+```
+⚠️  You are about to discard branch 'feature/my-feature'.
+    This will permanently delete all uncommitted and committed changes on this branch.
+    Type the branch name to confirm: feature/my-feature
+```
+
+```bash
+# After confirmation:
+git checkout main
+git branch -D feature/my-feature
+# If worktree exists:
+git worktree remove .worktrees/my-feature
+```
+
+**When to use**: Abandoned experiments, superseded approaches.
+
+丟棄操作需要使用者明確確認（輸入分支名稱），防止誤刪。
+
+---
+
+## Decision Flow
+
+```
+Prerequisites pass?
+  ├── No → Fix issues first
+  └── Yes → Choose completion option:
+        ├── 1. Merge locally
+        ├── 2. Create PR
+        ├── 3. Keep as-is
+        └── 4. Discard (requires confirmation)
+```
+
+---
+
+## Worktree Integration
+
+If the branch has an associated worktree, the worktree must be cleaned up as part of the completion process:
+
+| Completion Option | Worktree Action |
+|------------------|----------------|
+| Merge locally | Remove worktree after merge |
+| Create PR | Keep worktree until PR is merged |
+| Keep as-is | Keep worktree |
+| Discard | Remove worktree immediately |
+
+---
+
+## Rules
+
+| ID | Trigger | Action | Priority |
+|----|---------|--------|----------|
+| BC-001 | User selects Discard | Require branch name confirmation | Critical |
+| BC-002 | Branch has associated worktree | Clean up worktree on completion | High |
+| BC-003 | Prerequisites not met | Block completion, show failing checks | High |
+| BC-004 | Branch idle for 14+ days | Notify user to complete or discard | Medium |
+
+---
+
+## References
+
+- **Superpowers**: [finishing-a-development-branch](https://github.com/obra/superpowers) (MIT)
+- **Git Flow**: Branch lifecycle management
+- **Trunk-Based Development**: Short-lived branches pattern

package/bundled/core/change-batching-standards.md

@@ -0,0 +1,257 @@
+# Change Batching Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/change-batching-standards.md)
+
+**Applicability**: All software projects using automated development pipelines
+**Scope**: universal
+
+---
+
+## Overview
+
+Change Batching Standards define how pending changes should be accumulated, evaluated, and merged into atomic commits. This standard addresses the gap between making individual changes and committing them, providing rules for when and how to batch multiple related changes into cohesive units.
+
+## References
+
+| Standard/Source | Content |
+|----------------|---------|
+| SWEBOK v4.0 Chapter 6 | Software Configuration Management |
+| ISO/IEC 12207 | Configuration Management Process |
+| Continuous Delivery (Jez Humble) | Small batch sizes principle |
+| Lean Software Development | Batch size optimization |
+
+---
+
+## Pending Changes State Machine
+
+### State Definitions
+
+```
+┌─────────┐    threshold met    ┌─────────┐    merge success    ┌─────────┐
+│ PENDING │───────────────────▶│  READY  │────────────────────▶│ MERGED  │
+│ 等待中   │                    │ 就緒     │                     │ 已合併   │
+└─────────┘                    └─────────┘                     └─────────┘
+     ▲                              │                               │
+     │ reset                        │ merge failure                 │
+     │                              ▼                               ▼
+     │                        ┌─────────┐                    ┌──────────┐
+     └────────────────────────│ FAILED  │                    │ ARCHIVED │
+                              │ 失敗     │                    │ 已歸檔    │
+                              └─────────┘                    └──────────┘
+```
+
+### State Transitions
+
+| From | To | Trigger | Action |
+|------|----|---------|--------|
+| PENDING | PENDING | New change added | Increment counters, re-evaluate thresholds |
+| PENDING | READY | Threshold met | Prepare merge batch, run pre-merge validation |
+| READY | MERGED | Merge succeeds | Create commit, clear batch, archive |
+| READY | FAILED | Merge fails | Log failure, preserve changes |
+| FAILED | PENDING | Reset | Re-queue changes, clear failure state |
+| MERGED | ARCHIVED | Post-commit | Record batch metadata for audit |
+
+---
+
+## Threshold Strategies
+
+### Threshold Types
+
+| Strategy | Parameter | Default | Description |
+|----------|-----------|---------|-------------|
+| **Count** | `maxChanges` | 5 | Merge after N individual changes accumulated |
+| **Score** | `maxScore` | 10 | Merge when cumulative change score ≥ M |
+| **Time** | `maxAge` | 30m | Merge when oldest pending change exceeds TTL |
+| **Manual** | — | — | Merge only on explicit user request |
+
+### Change Scoring
+
+Each change is assigned a score based on complexity:
+
+| Change Type | Score | Example |
+|------------|-------|---------|
+| Trivial | 1 | Typo fix, whitespace, comment update |
+| Minor | 2 | Single function change, variable rename |
+| Standard | 3 | New function, modified logic flow |
+| Complex | 5 | Multi-file change, API modification |
+| Critical | 8 | Schema change, breaking change |
+
+### Threshold Configuration
+
+```json
+{
+  "batching": {
+    "strategy": "count",
+    "maxChanges": 5,
+    "maxScore": 10,
+    "maxAge": "30m",
+    "fallbackStrategy": "time"
+  }
+}
+```
+
+### Composite Thresholds
+
+Multiple thresholds can be combined with OR logic (first threshold met triggers merge):
+
+```
+Merge when: changes ≥ 5 OR score ≥ 10 OR age ≥ 30m
+```
+
+---
+
+## Merge Rules
+
+### Priority Order
+
+1. **Same-spec affinity**: Changes referencing the same SPEC-ID merge together first
+2. **Same-file grouping**: Changes to the same file(s) merge together
+3. **Dependency order**: Changes with dependencies merge in dependency order
+4. **Chronological**: Within same priority, merge in creation order
+
+### Conflict Resolution
+
+| Conflict Type | Resolution Strategy | Fallback |
+|--------------|-------------------|----------|
+| Same line, same file | Latest change wins | Manual resolution |
+| Overlapping functions | Semantic merge if possible | Manual resolution |
+| Dependency conflict | Resolve dependency first | Reject batch, split |
+
+### Pre-Merge Validation
+
+Before merging a batch, validate:
+
+| Check | Required | Description |
+|-------|----------|-------------|
+| All tests pass | Yes | Run test suite against merged state |
+| No lint errors | Yes | Run linter on merged files |
+| No conflicts | Yes | Verify clean merge without conflicts |
+| AC coverage maintained | Recommended | AC coverage not decreased |
+
+---
+
+## Atomicity Guarantees
+
+### All-or-Nothing Principle
+
+A batch merge MUST be atomic:
+
+- **Success**: ALL changes in the batch are committed together
+- **Failure**: NO changes from the batch are committed; all revert to PENDING
+
+### Atomicity Rules
+
+| Rule | Description |
+|------|-------------|
+| **Single commit** | Each merged batch produces exactly one commit |
+| **No partial merge** | If any change in the batch fails validation, the entire batch is rejected |
+| **Rollback support** | Failed merges MUST restore all changes to PENDING state |
+| **Isolation** | Batch merge MUST NOT affect changes outside the batch |
+
+---
+
+## Rollback Mechanism
+
+### Failure Handling
+
+When a batch merge fails:
+
+1. **Log failure**: Record which changes were in the batch and what failed
+2. **Preserve changes**: All changes return to PENDING state
+3. **Diagnose**: Identify the failing change(s)
+4. **Options**:
+   - Fix the failing change and retry
+   - Remove the failing change and merge the rest
+   - Split the batch into smaller groups
+
+### Rollback Triggers
+
+| Trigger | Action | Automatic? |
+|---------|--------|-----------|
+| Test failure | Reject entire batch | Yes |
+| Lint error | Reject entire batch | Yes |
+| Merge conflict | Reject and notify | Yes |
+| Build failure | Reject entire batch | Yes |
+| Manual rejection | Return to PENDING | No |
+
+---
+
+## Batch Commit Message Format
+
+Batched commits SHOULD use a structured message format:
+
+```
+<type>(<scope>): <summary of batch>
+
+Changes included:
+- <change 1 description>
+- <change 2 description>
+- <change 3 description>
+
+Spec: SPEC-XXX (if applicable)
+Batch: N changes, score M
+```
+
+### Example
+
+```
+feat(auth): implement login validation and error handling
+
+Changes included:
+- Add email format validation
+- Add password strength check
+- Add error message display
+- Add rate limiting for failed attempts
+
+Spec: SPEC-001
+Batch: 4 changes, score 11
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Impact | Correct Approach |
+|--------------|--------|------------------|
+| Infinite accumulation | Massive, unreviewable commits | Set reasonable thresholds |
+| Mixing unrelated changes | Hard to review, hard to revert | Group by spec or feature |
+| Partial commits | Broken intermediate states | Enforce atomicity |
+| Ignoring failures | Broken code enters codebase | Always validate before merge |
+| No rollback plan | Lost changes on failure | Preserve changes on failure |
+
+---
+
+## Best Practices
+
+### Do's
+
+- ✅ Set explicit thresholds for automatic batching
+- ✅ Group changes by specification or feature
+- ✅ Validate the entire batch before committing
+- ✅ Use atomic commits (all-or-nothing)
+- ✅ Preserve changes on failure
+- ✅ Log batch decisions for audit
+
+### Don'ts
+
+- ❌ Accumulate changes indefinitely
+- ❌ Mix unrelated changes in one batch
+- ❌ Commit partial batches
+- ❌ Ignore validation failures
+- ❌ Lose changes on merge failure
+
+---
+
+## Related Standards
+
+- [Check-in Standards](checkin-standards.md) — Quality gates for commits
+- [Pipeline Integration Standards](pipeline-integration-standards.md) — Pipeline automation
+- [Commit Message Guide](commit-message-guide.md) — Commit message format
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-03-18 | Initial version — state machine, threshold strategies, atomicity guarantees |

package/bundled/core/checkin-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/checkin-standards.md)
 
-**Version**: 1.4.0
-**Last Updated**: 2026-01-16
+**Version**: 1.5.0
+**Last Updated**: 2026-03-18
 **Applicability**: All software projects using version control
 **Scope**: partial
 **Industry Standards**: SWEBOK v4.0 Chapter 6
@@ -78,6 +78,11 @@ pip install -r requirements.txt && python -m py_compile src/**/*.py
   - Coverage percentage not decreased
   - Critical paths are tested
 
+- [ ] **AC coverage verified** (if using specification-driven workflow)
+  - All Acceptance Criteria have corresponding tests (see [Acceptance Criteria Traceability](acceptance-criteria-traceability.md))
+  - AC coverage meets project threshold (default: 80% for check-in)
+  - No previously covered AC regressed to uncovered
+
 **Project-Specific Test Commands**:
 ```bash
 # Example: .NET project
@@ -189,11 +194,11 @@ dotnet list package --vulnerable
   - Breaking changes noted
   - Setup instructions current
 
-- [ ] **CHANGELOG updated (if applicable)**
-  - For user-facing changes: entry added to `[Unreleased]` section
+- [ ] **CHANGELOG updated (pre-release only)**
+  - CHANGELOG is updated during release preparation, not per commit
+  - For user-facing changes: entry added to `[Unreleased]` section before release
   - Breaking changes marked with **BREAKING** prefix
-  - Follow exclusion rules in [versioning.md](versioning.md) and [changelog-standards.md](changelog-standards.md)
-  - Note: Internal refactoring, test-only, docs-only changes typically don't need CHANGELOG entries
+  - See [changelog-standards.md](changelog-standards.md) for timing per workflow
 
 **Documentation Formats**:
 ```
@@ -398,6 +403,7 @@ During development workflow execution, the following events should trigger check
 | Change Accumulation | Files ≥5 or lines ≥200 | Suggest |
 | Consecutive Skips | Skipped check-in 3 times | Warning |
 | Work Complete | Uncommitted changes before finishing | Strongly Recommend |
+| Batch Threshold | Pending changes reach configured threshold | Suggest |
 
 ### Reminder Behavior
 
@@ -430,6 +436,33 @@ During development workflow execution, the following events should trigger check
 └────────────────────────────────────────────────┘
 ```
 
+### Batch Threshold Trigger
+
+When using automated pipelines with change batching (see [Change Batching Standards](change-batching-standards.md)):
+
+- **Count threshold**: Trigger when accumulated changes ≥ configured `maxChanges`
+- **Score threshold**: Trigger when cumulative change score ≥ configured `maxScore`
+- **Time threshold**: Trigger when oldest pending change exceeds configured `maxAge`
+- **Behavior**: Batch threshold triggers a check-in suggestion, not automatic commit (unless `autoCheckin` is enabled)
+
+### Automated Check-in
+
+When `autoCheckin` is enabled in pipeline configuration (see [Pipeline Integration Standards](pipeline-integration-standards.md)):
+
+| Precondition | Required | Description |
+|-------------|----------|-------------|
+| All tests pass | Yes | Full test suite passes including new tests |
+| Lint clean | Yes | No lint errors in changed files |
+| AC coverage met | Yes | AC coverage meets project threshold |
+| No conflicts | Yes | Clean merge with target branch |
+| Batch validated | Yes (if batching) | All changes in batch validated together |
+
+**Safety Rules**:
+- Automated check-in MUST NOT push to protected branches
+- Automated check-in MUST create a proper commit message (not "auto-commit")
+- Automated check-in MUST be auditable (log who/what/when)
+- Users can always override with manual commit
+
 ### Skip Tracking
 
 When user chooses "commit later":
@@ -953,6 +986,7 @@ git commit -m "feat(module-c): add export to CSV feature"
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.5.0 | 2026-03-18 | Added: AC coverage verification, batch threshold trigger, automated check-in rules |
 | 1.4.0 | 2026-01-16 | Added: Bug Fix Testing Evaluation section with decision matrix |
 | 1.3.0 | 2026-01-05 | Added: SWEBOK v4.0 Chapter 6 (Software Configuration Management) to References |
 | 1.2.5 | 2025-12-16 | Clarified: CHANGELOG update is for user-facing changes only, added to [Unreleased] section |
@@ -972,6 +1006,9 @@ git commit -m "feat(module-c): add export to CSV feature"
 - [Commit Message Guide](commit-message-guide.md)
 - [Code Review Checklist](code-review-checklist.md)
 - [Deployment Standards](deployment-standards.md) - Quality gates feed into deployment readiness
+- [Acceptance Criteria Traceability](acceptance-criteria-traceability.md) - AC coverage verification
+- [Change Batching Standards](change-batching-standards.md) - Batch threshold triggers
+- [Pipeline Integration Standards](pipeline-integration-standards.md) - Automated check-in
 
 ---