know-thy-build 0.7.1 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "know-thy-build",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Multi-agent project definition & QA framework for Claude Code — Socratic dialogue, behavioral testing axes, design intent, orchestrated review",
   "bin": {
     "know-thy-build": "./bin/cli.js"

package/templates/know-thy-build/feature.md

@@ -375,6 +375,8 @@ gate:
   architect: pending
   designer: pending    # set to 'skipped' for non-UI features
   qa: pending
+  integration: pending # set by finish — auto-passed if no conflicts
+  ci: pending          # set by finish — runs project test command
 assumptions:
   - "{{assumption}}"
 date: {{date}}
@@ -384,10 +386,12 @@ generatedBy: know-thy-build-feature
 
 **Gate initialization rules:**
 - **Spike**: No gate field. Spikes produce answers, not implementations.
-- **Bounded (non-UI)**: `architect: pending`, `designer: skipped`, `qa: pending`
-- **Bounded (UI)**: `architect: pending`, `designer: pending`, `qa: pending`
+- **Bounded (non-UI)**: `architect: pending`, `designer: skipped`, `qa: pending`, `integration: pending`, `ci: pending`
+- **Bounded (UI)**: `architect: pending`, `designer: pending`, `qa: pending`, `integration: pending`, `ci: pending`
 - **Architectural**: All `pending`
 
+`integration` and `ci` gates are always initialized as `pending`. They are set by `/know-thy-build:finish` during the merge pipeline — never manually.
+
 **Priority guide:**
 - **P0**: Must-have for MVP. Without this, the project doesn't deliver its core value.
 - **P1**: Important. Significantly improves the experience but the project works without it.

package/templates/know-thy-build/finish.md

@@ -1,19 +1,19 @@
 ---
 description: Merge a completed feature — checks all review gates, squash merges to main, cleans up worktree. The final step in the feature lifecycle.
-allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Agent, AskUserQuestion]
 ---
 
 # Know Thy Build — Finish
 
-You are the **release gate**. Your job is to verify that all review gates have passed, then merge the feature to main and clean up.
+You are the **release gate**. Your job is to verify that all review gates have passed, rebase on main, handle conflicts, run CI, and then merge.
 
-You do NOT implement, review, or test. You only verify the gate and execute the merge.
+You do NOT implement features. You verify, resolve, review, and merge.
 
 ## Language
 
 **All conversation and output MUST be in: {{LANG}}**
 
-Technical terms (e.g. merge, squash, worktree, gate) stay in English. Everything else uses the specified language.
+Technical terms (e.g. merge, squash, worktree, gate, rebase, conflict) stay in English. Everything else uses the specified language.
 
 ---
 
@@ -40,41 +40,65 @@ FEATURE_FILE="docs/features/$(printf '%03d' $FEATURE_NUM).md"
 
 Read the feature spec and extract the gate section from frontmatter.
 
+### 3. Read project operations
+
+```bash
+# Check for project-specific merge/deploy/test requirements
+grep -A 30 '## Operations' docs/PROJECT.md 2>/dev/null
+```
+
+Extract:
+- **Test command** from CI/CD table (REQUIRED for ci gate)
+- **Merge strategy** (default: squash)
+- **Additional gates** (informational)
+
+If no test command is defined in Operations:
+> "⚠️ No test command found in docs/PROJECT.md → Operations → CI/CD. The `ci` gate will auto-pass. Consider defining a test command to catch regressions."
+
 ---
 
-## Gate Check
+## Phase 1: Review Gate Check
 
 Read the `gate:` section from the feature spec's YAML frontmatter.
 
 ### Display gate status
 
-Present a clear gate status report:
-
 ```
-🚦 Gate Check — Feature {{NNN}}: {{title}}
+🚦 Review Gate Check — Feature {{NNN}}: {{title}}
 
-  Architect:  {{status}}  {{date if passed}}
-  Designer:   {{status}}  {{date if passed}}
-  QA:         {{status}}  {{date if passed}}
+  Architect:    {{status}}  {{date if passed}}
+  Designer:     {{status}}  {{date if passed}}
+  QA:           {{status}}  {{date if passed}}
+  Integration:  pending     (set by this pipeline)
+  CI:           pending     (set by this pipeline)
 ```
 
-### Evaluate
+### Evaluate review gates
 
-**All gates `passed` or `skipped`:**
-> "All gates passed. Ready to merge."
-→ Proceed to Pre-merge Verification.
+Check only `architect`, `designer`, and `qa` at this stage. `integration` and `ci` are set by THIS pipeline — they are expected to be `pending`.
 
-**Any gate is `pending`:**
+**All review gates `passed` or `skipped`:**
+> "Review gates passed. Starting merge pipeline."
+→ Proceed to Phase 2.
+
+**Any review gate is `pending`:**
 > "Cannot merge — pending reviews:"
 > - `{{role}}`: pending — run `/know-thy-build:{{role}}` to complete
 
-→ Stop here. Do NOT proceed with merge.
+→ Stop here. Do NOT proceed.
 
----
+### Project-specific gates (informational)
 
-## Pre-merge Verification
+If `docs/PROJECT.md` has an Operations → Additional Gates section, report them:
+- **Code review required?** → Verify PR was reviewed (or inform the user)
+- **CI must pass?** → Will be checked in Phase 4
+- **Other gates?** → Report status
 
-Before merging, verify the worktree is in a clean, mergeable state:
+> These are informational. know-thy-build enforces its own gates; project-specific gates are the project's responsibility.
+
+---
+
+## Phase 2: Rebase on Main
 
 ### 1. Check for uncommitted changes
 
@@ -96,68 +120,188 @@ If any remain:
 > "Implementation markers found — the feature is not fully implemented."
 → Stop here.
 
-### 3. Verify tests pass
+### 3. Fetch and rebase
 
 ```bash
-# Detect test runner from package.json, pyproject.toml, etc.
-# Run appropriate test command
+git fetch origin main
+git rebase origin/main
 ```
 
-If tests fail:
-> "Tests are failing. Fix before merge."
-→ Stop here.
+**If rebase succeeds with no conflicts:**
+> "✅ Rebased cleanly on main. No conflicts."
+→ Set `integration: passed` in feature spec. Skip Phase 3. Proceed to Phase 4.
+
+**If rebase produces conflicts:**
+> "⚠️ Conflicts detected during rebase. Starting conflict resolution."
+→ Proceed to Phase 3.
+
+---
+
+## Phase 3: Conflict Resolution & Integration Review
+
+### Step 1: Identify conflicts
+
+```bash
+git diff --name-only --diff-filter=U
+```
+
+List every conflicting file. For each, show the conflict markers:
+
+```bash
+grep -n "<<<<<<< HEAD\|=======\|>>>>>>>" {{file}} 2>/dev/null
+```
+
+### Step 2: Understand the other side
+
+Before resolving, read what changed on main since the feature branched:
+
+```bash
+# What features were merged to main while this feature was in progress?
+git log --oneline origin/main --not $(git merge-base HEAD origin/main) -- docs/features/
+```
+
+Read the specs of recently merged features to understand their intent.
+
+### Step 3: Resolve conflicts
+
+For each conflict:
+
+1. Read both sides (ours = this feature, theirs = main)
+2. Understand the intent of both changes
+3. Resolve by preserving BOTH intents where possible
+4. If the intents are fundamentally incompatible → ask the user
 
-### 4. Verify artifacts exist
+After resolving each file:
+```bash
+git add {{file}}
+```
+
+After all conflicts resolved:
+```bash
+git rebase --continue
+```
+
+If additional conflicts appear in subsequent commits, repeat.
+
+### Step 4: Integration review agent
+
+**Dispatch a sub-agent** to review the conflict resolution:
+
+```
+Agent prompt:
+"You are the integration reviewer. Your job is to verify that conflict resolution
+preserved the intent of ALL affected features, introduced no side effects, and
+maintained architectural consistency.
+
+Context:
+- This feature: docs/features/{{NNN}}.md
+- Recently merged features: [list from Step 2]
+- Project rules: docs/PROJECT.md, docs/TECHNICAL.md
+
+Tasks:
+1. Read this feature's spec and all recently merged feature specs
+2. Read the conflict resolution diff: git diff HEAD~1 (or appropriate range)
+3. For each resolved conflict:
+   a. Does the resolution preserve BOTH features' intent?
+   b. Does it introduce any side effect on either feature's code paths?
+   c. Does it follow the patterns in TECHNICAL.md?
+4. Check if regression guard tests exist for the affected areas
+5. Report: PASSED (all clear) or FAILED (list specific issues)
+
+Be aggressive — you are the last defense before merge. If you have doubts,
+report them as failures. False negatives (missed bugs) are worse than false
+positives (extra review)."
+```
+
+**If integration review returns PASSED:**
+→ Set `integration: passed` in feature spec. Proceed to Phase 4.
+
+**If integration review returns FAILED:**
+> "❌ Integration review failed:"
+> {{list specific issues from the agent}}
+> "Fix the issues and re-run `/know-thy-build:finish`."
+→ Set `integration: failed` in feature spec. Stop here.
+
+---
+
+## Phase 4: CI/CD Gate
+
+### 1. Run test command
 
-Check that each role left its artifacts in the worktree:
+Extract the test command from `docs/PROJECT.md` → Operations → CI/CD:
 
 ```bash
-# Architect artifacts: scaffold files, signature tests
-grep -rn "DO NOT MODIFY" --include="*.test.*" --include="*_test.*" . 2>/dev/null | head -5
+# Example: npm test, pytest, go test ./...
+{{test_command}}
+```
+
+**If no test command is defined:** auto-pass with warning.
+
+### 2. Run additional CI checks (if defined)
 
-# QA artifacts: test cases in QA.md
-grep -c "Feature {{NNN}}" docs/QA.md 2>/dev/null
+If Operations defines lint, type check, or other blocking checks:
+
+```bash
+# Example: eslint ., tsc --noEmit
+{{ci_check_commands}}
 ```
 
-Report what will be merged to main:
-> "The following artifacts from this feature will be merged to main:"
-> - Code: {{list of modified/new source files}}
-> - Architect: scaffold structure, signature tests
-> - Designer: design intent updates in feature spec (if applicable)
-> - QA: test cases in `docs/QA.md`
-> - Feature spec: gate statuses updated
+### 3. Evaluate
+
+**All CI checks pass:**
+→ Set `ci: passed` in feature spec. Proceed to Phase 5.
+
+**Any CI check fails:**
+> "❌ CI failed:"
+> {{error output}}
+> "Fix the failures and re-run `/know-thy-build:finish`."
+→ Set `ci: failed` in feature spec. Stop here.
 
 ---
 
-## Merge
+## Phase 5: Merge
+
+All 5 gates are now `passed` or `skipped`. Proceed with merge.
+
+### 1. Determine merge strategy
 
-### 1. Switch to main and merge
+Check `docs/PROJECT.md` → Operations → Merge Strategy. Default to squash if not defined.
+
+| Strategy | Command |
+|----------|---------|
+| squash (default) | `git merge --squash` |
+| rebase | fast-forward merge (already rebased) |
+| merge commit | `git merge --no-ff` |
+
+### 2. Switch to main and merge
 
 ```bash
 # Ensure main is up to date
 git checkout main
 git pull --ff-only origin main 2>/dev/null || true
 
-# Squash merge
+# Execute the merge strategy (default: squash)
 git merge --squash "feature/{{NNN}}-{{title_kebab}}"
 ```
 
-### 2. Create commit
+### 3. Create commit
 
 ```bash
 git commit -m "feat({{NNN}}): {{title}}
 
 - Architect: {{brief summary of structure decisions}}
 - Designer: {{brief summary of design decisions, or 'skipped'}}
-- QA: {{number}} test cases passed
+- QA: {{number}} test cases, {{number}} regression guards
+- Integration: {{clean / resolved N conflicts}}
+- CI: all checks passed
 
 Feature spec: docs/features/{{NNN}}.md
-Gate: architect ✓ | designer ✓/skipped | qa ✓"
+Gate: architect ✓ | designer ✓/skipped | qa ✓ | integration ✓ | ci ✓"
 ```
 
-### 3. Update feature spec status
+### 4. Update feature spec status
 
-Switch back briefly or edit from main — update the feature spec frontmatter:
+Update the feature spec frontmatter:
 
 ```yaml
 status: complete
@@ -166,9 +310,11 @@ gate:
   architect: passed
   designer: passed  # or skipped
   qa: passed
+  integration: passed
+  ci: passed
 ```
 
-### 4. Update Feature Registry
+### 5. Update Feature Registry
 
 In `docs/PROJECT.md`, update the Feature Registry row for this feature:
 ```
@@ -215,6 +361,13 @@ Commit: {{short hash}} feat({{NNN}}): {{title}}
 Branch: feature/{{NNN}}-{{title_kebab}} — deleted
 Worktree: {{WT_PATH}} — removed
 
+Pipeline results:
+  Architect:    ✓ passed
+  Designer:     ✓ passed / skipped
+  QA:           ✓ passed ({{N}} test cases, {{N}} regression guards)
+  Integration:  ✓ {{clean / resolved N conflicts}}
+  CI:           ✓ all checks passed
+
 Artifacts merged:
   - Code changes: {{file count}} files
   - Architect structure: preserved in code + signature tests
@@ -229,17 +382,30 @@ Next: /know-thy-build:feature for the next feature
 
 ## Edge Cases
 
-### Merge conflicts
+### Rebase conflicts that can't be auto-resolved
+
+If conflicts involve fundamentally incompatible changes (e.g. two features restructured the same module differently):
+
+1. Show both sides with full context
+2. Read both feature specs to understand intent
+3. Propose a resolution that preserves both intents
+4. Ask the user to confirm before proceeding
+5. The integration review agent will verify the resolution
+
+### Integration review fails repeatedly
+
+If the integration review agent keeps finding issues after fixes:
+
+1. Show the full list of unresolved issues
+2. Suggest the user review the issues manually
+3. Offer to skip integration review with explicit user approval:
+   > "Skipping integration review at user's request. Set `integration: skipped` in feature spec."
 
-If `git merge --squash` produces conflicts:
+### No test command defined
 
-1. List conflicting files
-2. For each conflict, show the conflict markers
-3. Offer resolution options:
-   - Accept worktree version (ours)
-   - Accept main version (theirs)
-   - Manual resolution
-4. After resolution, continue with commit
+If `docs/PROJECT.md` doesn't define a test command:
+- `ci` gate auto-passes with a warning
+- Recommend the user runs `/know-thy-build:project` to define one
 
 ### Abandoned feature
 

package/templates/know-thy-build/project.md

@@ -551,6 +551,42 @@ Accumulate as:
 
 **Done when:** Frontier is empty. 2-7 principles captured, or user decides none are needed.
 
+### Operations — How does code ship?
+
+> What to discover: The project's merge, deploy, and CI workflow. know-thy-build enforces quality gates (architect/designer/qa) BEFORE merge. This area defines what happens AT and AFTER merge — which is project-specific.
+
+**Prerequisites:** Vision and Output areas settled.
+
+Before asking, **find facts** — scan existing infrastructure:
+```bash
+cat package.json 2>/dev/null | grep -E '"scripts"|"test"|"lint"|"build"|"deploy"' | head -10
+ls .github/workflows/ .gitlab-ci.yml Jenkinsfile Makefile Dockerfile 2>/dev/null
+cat .github/workflows/*.yml 2>/dev/null | head -40
+```
+
+Present what you found as facts, then ask about decisions:
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| How do feature branches merge to main? (squash, rebase, merge commit) | — | Decision |
+| **What is the test command?** (e.g. `npm test`, `pytest`, `go test ./...`) | — | Decision (REQUIRED) |
+| How does code reach users? (npm publish, docker, manual deploy, CI/CD trigger) | — | Decision |
+| What other automated checks run before merge? (lint, type check) | merge-strategy | Fact (scan CI config) + Decision |
+| Are there review requirements beyond know-thy-build gates? (code review, security scan) | — | Decision |
+
+Slots to fill:
+- `{{merge_strategy}}` — squash / rebase / merge commit
+- `{{test_command}}` — **REQUIRED.** The command `/know-thy-build:finish` runs before merge. Without it, the `ci` gate auto-passes.
+- `{{deploy_method}}` — how releases reach users
+- `{{ci_checks}}` — automated quality checks (lint, type check, etc.)
+- `{{additional_gates}}` — extra review requirements
+
+**Done when:** Frontier is empty. At minimum, merge strategy and **test command** are defined. Deploy and additional gates can be "none yet" if the project is early.
+
+> **Why this matters:** Without explicit operations definitions, sub-agents and hooks cannot enforce project-specific workflows. The merge gate hook only covers know-thy-build's built-in gates — project-specific gates (code review, CI checks) must be defined here so agents know to respect them.
+
 ---
 
 ## Checkpoints & State Tracking
@@ -781,6 +817,55 @@ Remove `areasRemaining`, `lastCheckpoint`, and `open` counts.
 
 **Technical Foundation:** [TECHNICAL.md](TECHNICAL.md)
 
+## Operations
+
+<!-- How this project ships code. Each project defines its own workflow.
+     know-thy-build gates (architect/designer/qa) enforce quality BEFORE merge.
+     Everything below defines what happens AT and AFTER merge. -->
+
+### Merge Strategy
+
+<!-- How feature branches become main. know-thy-build defaults to squash merge,
+     but your project may differ. -->
+
+| Setting | Value |
+|---------|-------|
+| **Strategy** | {{squash / rebase / merge commit}} |
+| **Branch naming** | `feature/NNN-slug` (know-thy-build default) |
+| **Commit format** | `feat(NNN): title` |
+
+### Deploy
+
+<!-- How main reaches users. Leave blank if not yet decided. -->
+
+| Setting | Value |
+|---------|-------|
+| **Method** | {{npm publish / docker push / manual / CI-triggered / N/A}} |
+| **Target** | {{registry, server, CDN, etc.}} |
+| **Trigger** | {{on tag / on merge to main / manual}} |
+
+### CI/CD
+
+<!-- Automated checks that run on push or PR.
+     The test command is REQUIRED — /know-thy-build:finish runs it before merge.
+     Without it, the ci gate auto-passes and regressions slip through. -->
+
+| Check | Command | Blocks merge? |
+|-------|---------|---------------|
+| **test** | **{{test_command}}** | **yes (required)** |
+| {{lint}} | {{eslint, ruff, etc.}} | {{yes/no}} |
+| {{type check}} | {{tsc, mypy, etc.}} | {{yes/no}} |
+
+### Additional Gates
+
+<!-- Review requirements beyond know-thy-build's built-in gates.
+     Only include gates that actually exist or are planned. Omit if none. -->
+
+| Gate | Required? | Who |
+|------|-----------|-----|
+| {{code review}} | {{yes/no}} | {{team lead, any reviewer, etc.}} |
+| {{security scan}} | {{yes/no}} | {{tool name}} |
+
 ---
 
 *Generated by know-thy-build | {{date}}*
@@ -930,8 +1015,13 @@ worktree (sub-agent orchestrates the entire lifecycle):
     Designer review  → gate.designer ✓
     QA TEST          → gate.qa ✓
 
-  Phase 4 — Finish:
-    All gates passed → /know-thy-build:finish → squash merge + cleanup
+  Phase 4 — Finish (merge pipeline):
+    /know-thy-build:finish orchestrates:
+      Review gates check     → architect/designer/qa must be passed
+      Rebase on main         → surface conflicts
+      Conflict resolution    → resolve, then integration review agent
+      CI/CD                  → run project test command
+      Merge                  → squash merge + cleanup
 ```
 
 ### Gate (Merge Prerequisite)
@@ -943,6 +1033,8 @@ Merge is allowed only when all gates are `passed` or `skipped`.
 | architect | pending → passed | Architect review passes |
 | designer | pending → passed / skipped | Designer review passes (skipped for non-UI) |
 | qa | pending → passed | All QA test cases pass |
+| integration | pending → passed | Finish: rebase clean OR conflict review agent passes |
+| ci | pending → passed | Finish: project test command passes |
 
 ### Orchestrator Model
 The user session acts as **orchestrator only** — it does NOT implement directly.
@@ -959,7 +1051,20 @@ Before any work, the sub-agent MUST read:
 - Architect + Designer re-review if changes are structural
 - QA re-tests failed scenarios + regression check on happy path
 - Loop continues until ALL reviewers' criteria are `[x]`
-- Only when all three gates pass does `/know-thy-build:finish` proceed
+- Only when all three review gates pass does `/know-thy-build:finish` start the merge pipeline
+- Finish then handles: rebase → conflict resolution → integration review → CI → merge
+
+### Project-Specific Operations
+The merge gate hook enforces know-thy-build's built-in gates (architect/designer/qa).
+Your project may have additional requirements defined in `docs/PROJECT.md` → Operations section:
+- **Merge strategy** — the hook assumes squash merge; adjust if your project uses rebase or merge commits
+- **CI/CD checks** — if your project requires CI to pass before merge, enforce that separately
+- **Additional gates** — code review, security scan, etc. are project-level concerns, not managed by know-thy-build
+- **Deploy** — what happens after merge is entirely project-defined
+
+When `/know-thy-build:finish` runs, it checks know-thy-build gates. For project-specific gates, the project should either:
+1. Add its own hooks to `.claude/settings.json`
+2. Or rely on CI/CD and branch protection rules
 
 ### Document References
 - Project definition: `docs/PROJECT.md`
@@ -967,6 +1072,7 @@ Before any work, the sub-agent MUST read:
 - Feature specs: `docs/features/NNN.md`
 - QA test cases: `docs/QA.md`
 - Feature registry: `docs/PROJECT.md` → Feature Registry section
+- Operations: `docs/PROJECT.md` → Operations section
 ```
 
 ## Setup Merge Gate Hook
@@ -981,22 +1087,27 @@ After generating CLAUDE.md, set up the merge gate hook in `.claude/settings.json
 #!/usr/bin/env bash
 # know-thy-build merge gate — blocks git merge when feature gate is not fully passed
 
-# Only check if the command contains git merge
-if ! echo "$TOOL_INPUT" | grep -qE 'git\s+merge'; then
-  exit 0
-fi
+# Fast exit: only check commands that contain "git merge"
+echo "${TOOL_INPUT:-}" | grep -qE 'git\s+merge' || exit 0
 
-# Find the active feature spec with gate
-FEATURE_FILE=$(ls -t docs/features/*.md 2>/dev/null | head -1)
-if [ -z "$FEATURE_FILE" ]; then
-  exit 0
-fi
+# Identify current feature from branch name (feature/NNN-slug)
+BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+echo "$BRANCH" | grep -qE '^feature/' || exit 0
+
+FEATURE_NUM=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
+[ -z "$FEATURE_NUM" ] && exit 0
+
+FEATURE_FILE="docs/features/$(printf '%03d' "$FEATURE_NUM").md"
+[ -f "$FEATURE_FILE" ] || exit 0
+
+# Skip completed features — their gate is historical, not active
+grep -qE '^status:\s*complete' "$FEATURE_FILE" 2>/dev/null && exit 0
 
 # Check gate statuses
-PENDING=$(grep -cE '^\s+(architect|designer|qa):\s*pending' "$FEATURE_FILE" 2>/dev/null || echo "0")
+PENDING=$(grep -cE '^\s+(architect|designer|qa|integration|ci):\s*pending' "$FEATURE_FILE" 2>/dev/null || echo "0")
 
 if [ "$PENDING" -gt 0 ]; then
-  echo "❌ Merge gate blocked — pending reviews exist:"
+  echo "❌ Merge gate blocked — Feature $(printf '%03d' "$FEATURE_NUM") has pending reviews:"
   grep -E '^\s+(architect|designer|qa):' "$FEATURE_FILE" 2>/dev/null
   echo ""
   echo "Run /know-thy-build:finish to check gate status."
@@ -1028,6 +1139,8 @@ exit 0
 
 Make the hook script executable: `chmod +x .claude/hooks/check-merge-gate.sh`
 
+> **Note for projects**: The `"matcher": "Bash"` fires on every Bash tool call but exits in < 1ms for non-merge commands (first `grep` short-circuits). Claude Code does not support content-based matchers, so this is the lightest possible approach.
+
 ## Closing
 
 **After CREATE:**

package/templates/know-thy-build/qa.md

@@ -685,13 +685,49 @@ For each selected profile, generate test cases using its **turn-level instructio
 - **Profile** column traces which behavioral axis combination generated this case.
 - **Injection test cases** must specify exactly how to inject the failure state.
 
-### Step 5: Update QA.md
+### Step 5: Regression Guard Tests (MANDATORY)
+
+**Purpose:** Protect this feature's core behavior from being broken by future feature merges. When multiple agents work on features in parallel, another agent's merge can silently break your work. Regression guard tests catch that.
+
+**Rules:**
+- Each **Done When** criterion in the feature spec → at least 1 automated test
+- Tests must be **independently runnable** — no cross-feature dependency
+- Tests must **fail loudly** when behavior changes, not silently pass
+- Test names include the feature number: `test_NNN_*` (e.g. `test_003_login_success`)
+- Tests run via the project's test command defined in `docs/PROJECT.md` → Operations → CI/CD
+
+**How to write regression guards:**
+
+1. Read the feature spec's **Done When** section
+2. For each criterion, write at least one automated test that:
+   - Sets up the precondition
+   - Performs the action
+   - Asserts the expected outcome
+   - Cleans up after itself (no side effects on other tests)
+3. Group tests under the feature number for traceability
+
+**Template:**
+
+```
+### Regression Guards — Feature {{NNN}}: {{title}}
+
+| # | Done-When Criterion | Test Name | What It Verifies |
+|---|---------------------|-----------|------------------|
+| 1 | {{criterion_1}} | test_{{NNN}}_{{name}} | {{specific assertion}} |
+| 2 | {{criterion_2}} | test_{{NNN}}_{{name}} | {{specific assertion}} |
+```
+
+**Why this matters:** When `/know-thy-build:finish` rebases on main and resolves conflicts, it runs the project's test command. If another feature's merge broke your work, your regression guard tests fail, and the merge is blocked. Without these tests, the CI gate is a formality.
+
+### Step 6: Update QA.md
 
 1. Append the feature section to `docs/QA.md`
 2. Add any new turn-level scenarios to the Turn-Level Scenarios section
-3. Update feature spec frontmatter:
+3. Add regression guard test entries to the feature section
+4. Update feature spec frontmatter:
    ```yaml
    qaTestCases: {{count}}
+   qaRegressionGuards: {{count}}
    qaReviewDate: {{date}}
    ```
 
@@ -699,6 +735,7 @@ For each selected profile, generate test cases using its **turn-level instructio
 - [ ] Every AC has at least one test case
 - [ ] At least 3 profiles are represented in test cases
 - [ ] At least 2 failure state injection test cases
+- [ ] **Every Done-When criterion has at least one regression guard test**
 - [ ] Access path verified
 - [ ] Test cases are concrete enough that anyone could execute them
 - [ ] Feature section appended to `docs/QA.md`