know-thy-build 0.7.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "know-thy-build",
-  "version": "0.7.1",
+  "version": "0.8.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/finish.md

@@ -40,6 +40,15 @@ 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 requirements
+grep -A 20 '## 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.
+
 ---
 
 ## Gate Check
@@ -70,6 +79,15 @@ Present a clear gate status report:
 
 → Stop here. Do NOT proceed with merge.
 
+### Project-specific gates (if defined)
+
+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
+
+> 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.
+
 ---
 
 ## Pre-merge Verification
@@ -131,14 +149,24 @@ Report what will be merged to main:
 
 ## Merge
 
-### 1. Switch to main and merge
+### 1. Determine merge strategy
+
+Check `docs/PROJECT.md` → Operations → Merge Strategy. Default to squash if not defined.
+
+| Strategy | Command |
+|----------|---------|
+| squash (default) | `git merge --squash` |
+| rebase | `git rebase main` then fast-forward merge |
+| 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 determined above (default: squash)
 git merge --squash "feature/{{NNN}}-{{title_kebab}}"
 ```
 

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

@@ -551,6 +551,40 @@ 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 |
+| 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 |
+| Are there review requirements beyond know-thy-build gates? (code review, security scan) | — | Decision |
+
+Slots to fill:
+- `{{merge_strategy}}` — squash / rebase / merge commit
+- `{{deploy_method}}` — how releases reach users
+- `{{ci_checks}}` — automated quality checks
+- `{{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.
+
+> **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 +815,53 @@ 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. -->
+
+| Check | Tool | Blocks merge? |
+|-------|------|---------------|
+| {{lint}} | {{eslint, ruff, etc.}} | {{yes/no}} |
+| {{type check}} | {{tsc, mypy, etc.}} | {{yes/no}} |
+| {{tests}} | {{jest, pytest, 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}}*
@@ -961,12 +1042,25 @@ Before any work, the sub-agent MUST read:
 - Loop continues until ALL reviewers' criteria are `[x]`
 - Only when all three gates pass does `/know-thy-build:finish` proceed
 
+### 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`
 - Technical foundation: `docs/TECHNICAL.md`
 - 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 +1075,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")
 
 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 +1127,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:**