know-thy-build 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "know-thy-build",
-  "version": "0.8.0",
+  "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.
 
 ---
 
@@ -43,56 +43,62 @@ Read the feature spec and extract the gate section from frontmatter.
 ### 3. Read project operations
 
 ```bash
-# Check for project-specific merge/deploy requirements
-grep -A 20 '## Operations' docs/PROJECT.md 2>/dev/null
+# Check for project-specific merge/deploy/test requirements
+grep -A 30 '## Operations' docs/PROJECT.md 2>/dev/null
 ```
 
-If an Operations section exists, note the project's merge strategy and additional gates. These are checked alongside know-thy-build gates below.
+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 (if defined)
+### Project-specific gates (informational)
 
-If `docs/PROJECT.md` has an Operations → Additional Gates section, check those too:
-- **Code review required?** → Verify PR was reviewed (or inform the user to do so)
-- **CI must pass?** → Check CI status or inform the user to verify
-- **Other gates?** → Report status of each
+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
 
-> These gates are informational — know-thy-build reports them but cannot enforce external systems. The user is responsible for ensuring project-specific gates pass before proceeding.
+> These are informational. know-thy-build enforces its own gates; project-specific gates are the project's responsibility.
 
 ---
 
-## Pre-merge Verification
-
-Before merging, verify the worktree is in a clean, mergeable state:
+## Phase 2: Rebase on Main
 
 ### 1. Check for uncommitted changes
 
@@ -114,40 +120,148 @@ 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.
+
+---
 
-### 4. Verify artifacts exist
+## Phase 3: Conflict Resolution & Integration Review
 
-Check that each role left its artifacts in the worktree:
+### Step 1: Identify conflicts
 
 ```bash
-# Architect artifacts: scaffold files, signature tests
-grep -rn "DO NOT MODIFY" --include="*.test.*" --include="*_test.*" . 2>/dev/null | head -5
+git diff --name-only --diff-filter=U
+```
+
+List every conflicting file. For each, show the conflict markers:
 
-# QA artifacts: test cases in QA.md
-grep -c "Feature {{NNN}}" docs/QA.md 2>/dev/null
+```bash
+grep -n "<<<<<<< HEAD\|=======\|>>>>>>>" {{file}} 2>/dev/null
 ```
 
-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
+### 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
+
+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
+
+Extract the test command from `docs/PROJECT.md` → Operations → CI/CD:
+
+```bash
+# 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)
+
+If Operations defines lint, type check, or other blocking checks:
+
+```bash
+# Example: eslint ., tsc --noEmit
+{{ci_check_commands}}
+```
+
+### 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
 
@@ -156,7 +270,7 @@ Check `docs/PROJECT.md` → Operations → Merge Strategy. Default to squash if
 | Strategy | Command |
 |----------|---------|
 | squash (default) | `git merge --squash` |
-| rebase | `git rebase main` then fast-forward merge |
+| rebase | fast-forward merge (already rebased) |
 | merge commit | `git merge --no-ff` |
 
 ### 2. Switch to main and merge
@@ -166,26 +280,28 @@ Check `docs/PROJECT.md` → Operations → Merge Strategy. Default to squash if
 git checkout main
 git pull --ff-only origin main 2>/dev/null || true
 
-# Execute the merge strategy determined above (default: squash)
+# 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
@@ -194,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:
 ```
@@ -243,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
@@ -257,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

@@ -571,17 +571,19 @@ 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 automated checks run before merge? (lint, type check, tests) | merge-strategy | Fact (scan CI config) + 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
+- `{{ci_checks}}` — automated quality checks (lint, type check, etc.)
 - `{{additional_gates}}` — extra review requirements
 
-**Done when:** Frontier is empty. At minimum, merge strategy and deploy method are defined. CI/CD and additional gates can be "none yet" if the project is early.
+**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.
 
@@ -844,13 +846,15 @@ Remove `areasRemaining`, `lastCheckpoint`, and `open` counts.
 
 ### CI/CD
 
-<!-- Automated checks that run on push or PR. -->
+<!-- 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 | Tool | Blocks merge? |
-|-------|------|---------------|
+| Check | Command | Blocks merge? |
+|-------|---------|---------------|
+| **test** | **{{test_command}}** | **yes (required)** |
 | {{lint}} | {{eslint, ruff, etc.}} | {{yes/no}} |
 | {{type check}} | {{tsc, mypy, etc.}} | {{yes/no}} |
-| {{tests}} | {{jest, pytest, etc.}} | {{yes/no}} |
 
 ### Additional Gates
 
@@ -1011,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)
@@ -1024,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.
@@ -1040,7 +1051,8 @@ 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).
@@ -1092,7 +1104,7 @@ FEATURE_FILE="docs/features/$(printf '%03d' "$FEATURE_NUM").md"
 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 — Feature $(printf '%03d' "$FEATURE_NUM") has pending reviews:"

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`