docs: add checkpoint commits, concern field, and merge cleanup to docs and tests

why: the contract and orchestrator skill evolved to support fast iteration with clean handoffs — docs and tests need to match

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: hunterassembly

CHANGELOG.md

@@ -12,6 +12,8 @@
 - Added multi-agent orchestrator support: `AGENT_ID` env var tags diary entries and findings.
 - Added `reconcile-branch.sh` merge-gate script for branch-scoped reconciliation.
 - Added `orchestrator` skill with coordination contract for multi-agent systems.
+- Added `concern:` field support in post-commit diary for agents to flag risky changes.
+- Added checkpoint commit support: `fixup!` / `squash!` commits skip format/why enforcement.
 - Added `bootstrap-harness.sh` to scaffold AGENTS/docs/evals for harness-engineering workflows.
 - Added `new-project-bootstrap.sh` for one-command skill install + repo setup.
 - Added `.agent/PLANS.md` execution-plan standard aligned with Codex Exec Plans.

README.md

@@ -102,9 +102,17 @@ git submodule add https://github.com/hunterassembly/dev-discipline.git .dev-disc
 - Blocks non-conventional commit messages (must be `type(scope): description`)
 - Blocks missing `why:` line
 - Blocks `why:` lines that are too short (<10 chars), restate the subject, or use filler phrases
+- Allows `fixup!` / `squash!` checkpoint commits during active implementation
 
 **post-commit:**
 - Silently appends commit metadata to `.dev/diary/YYYY-MM-DD.md`
+- Logs optional `concern:` lines from commit messages for reconciliation review
+
+### Commit cadence (speed + clean history)
+
+- During active implementation, use checkpoint commits (`fixup!` / `squash!`) when needed for speed.
+- Before review/merge, squash checkpoints into 1-3 concern-level commits with strong `why:` lines.
+- The quality bar applies at handoff, not every keystroke.
 
 ### At session boundaries (reconciliation)
 
@@ -190,6 +198,7 @@ Removes hooks and bridge references from AGENTS.md/CLAUDE.md. Does not delete `.
 - **The diary writes itself.** Post-commit logs metadata. AI summarizes later.
 - **Feedback loops close.** Reconciliation findings feed into the next session automatically.
 - **Multi-agent is just git.** Branches isolate, merges synchronize, hooks enforce per-branch. No coordination layer needed.
+- **Fast while building, clean at handoff.** Checkpoint commits are fine during execution; final history should be concern-level and reviewable.
 
 ## License
 

skills/orchestrator/SKILL.md

@@ -72,6 +72,11 @@ Every agent must, before writing code:
 
 Before merging an agent's branch:
 
+1. Clean up commit history on that branch:
+   - checkpoint `fixup!` / `squash!` commits are allowed during implementation,
+   - but handoff history should be consolidated into concern-level commits with clear `why:` lines.
+2. Run the branch reconciliation merge gate:
+
 ```bash
 scripts/reconcile-branch.sh agent/<agent-id>/<concern> --base main
 ```

tests/dev_discipline_integration_test.sh

@@ -407,6 +407,76 @@ test_orchestrator_skill_exists() {
   fi
 }
 
+test_commit_msg_allows_fixup_commits() {
+  local tmp_repo hook_output hook_code
+  tmp_repo=$(mktemp -d)
+  git init "$tmp_repo" >/dev/null 2>&1
+
+  local hook_src="$REPO_ROOT/skills/dev-discipline/assets/commit-msg"
+  cp "$hook_src" "$tmp_repo/.git/hooks/commit-msg"
+  chmod +x "$tmp_repo/.git/hooks/commit-msg"
+
+  local msg_file="$tmp_repo/.git/COMMIT_EDITMSG"
+  printf 'fixup! feat(auth): add rate limiting' > "$msg_file"
+
+  set +e
+  hook_output=$("$tmp_repo/.git/hooks/commit-msg" "$msg_file" 2>&1)
+  hook_code=$?
+  set -e
+
+  if [ "$hook_code" -eq 0 ]; then
+    pass "commit-msg allows fixup! checkpoint commits"
+  else
+    fail "commit-msg allows fixup! checkpoint commits (code=$hook_code)"
+  fi
+}
+
+test_commit_msg_allows_squash_commits() {
+  local tmp_repo hook_output hook_code
+  tmp_repo=$(mktemp -d)
+  git init "$tmp_repo" >/dev/null 2>&1
+
+  local hook_src="$REPO_ROOT/skills/dev-discipline/assets/commit-msg"
+  cp "$hook_src" "$tmp_repo/.git/hooks/commit-msg"
+  chmod +x "$tmp_repo/.git/hooks/commit-msg"
+
+  local msg_file="$tmp_repo/.git/COMMIT_EDITMSG"
+  printf 'squash! feat(auth): add rate limiting' > "$msg_file"
+
+  set +e
+  hook_output=$("$tmp_repo/.git/hooks/commit-msg" "$msg_file" 2>&1)
+  hook_code=$?
+  set -e
+
+  if [ "$hook_code" -eq 0 ]; then
+    pass "commit-msg allows squash! checkpoint commits"
+  else
+    fail "commit-msg allows squash! checkpoint commits (code=$hook_code)"
+  fi
+}
+
+test_post_commit_logs_concerns() {
+  local tmp_home tmp_repo
+  tmp_home=$(mktemp -d)
+  tmp_repo=$(mktemp -d)
+
+  HOME="$tmp_home" "$REPO_ROOT/scripts/new-project-bootstrap.sh" --init-git "$tmp_repo" >/dev/null 2>&1
+
+  (
+    cd "$tmp_repo"
+    echo "test" > testfile.txt
+    git add testfile.txt
+    git commit --no-verify -m "$(printf 'feat(auth): change login flow\n\nwhy: simplifying auth reduces attack surface\nconcern: this changes session handling — verify no active sessions break')" >/dev/null 2>&1
+  )
+
+  diary_file=$(ls "$tmp_repo/.dev/diary/"*.md 2>/dev/null | head -1)
+  if [ -n "$diary_file" ] && grep -q "verify no active sessions break" "$diary_file"; then
+    pass "post-commit logs concern: lines in diary"
+  else
+    fail "post-commit logs concern: lines in diary"
+  fi
+}
+
 test_bootstrap_installs_planner_and_scaffold
 test_pre_commit_blocks_large_source_change_without_plan_update
 test_planner_validator_checks_quality_rules
@@ -427,6 +497,9 @@ test_post_commit_tags_agent_id
 test_post_commit_no_tag_without_agent_id
 test_reconcile_branch_script_exists
 test_orchestrator_skill_exists
+test_commit_msg_allows_fixup_commits
+test_commit_msg_allows_squash_commits
+test_post_commit_logs_concerns
 
 echo ""
 echo "Test results: $PASS_COUNT passed, $FAIL_COUNT failed"