forge-workflow 0.0.3 → 0.0.4

package/.opencode/commands/status.md

@@ -16,60 +16,31 @@ This command helps you understand the current state of the project before starti
 
 ## What This Command Does
 
-### Step 1: Check Project Health
-```bash
-bd stats
-```
-- How many open / in-progress / completed issues?
-- Any blocked issues?
+## Step 0: Sync team state
 
-### Step 2: Check Active Work
 ```bash
-# Active Beads issues
-bd list --status in_progress
+# Sync team state before showing status
+bash scripts/sync-utils.sh auto-sync
 ```
 
-For each in-progress issue, show compact progress:
+### Step 1: Smart Status (ranked issues with conflict detection)
 ```bash
-bash scripts/beads-context.sh parse-progress <issue-id>
+bash scripts/smart-status.sh
 ```
-Display the compact output (e.g., "3/7 tasks done | Last: Validation logic (def5678)")
+This script dynamically computes and displays all issues ranked by composite score (priority, dependency impact, type, staleness, epic proximity). Output includes active sessions, conflict risk annotations, and grouped categories. No manual querying needed — the script handles everything.
 
-Hint: `bd show <id>` for full context on any issue.
+For full context on any issue: `bd show <id>`
 
-### Step 3: Review Recent Work
+### Step 2: Review Recent Commits
 ```bash
-# Recent commits
 git log --oneline -10
-
-# Recently completed Beads
-bd list --status completed --limit 5
 ```
 
-### Step 4: Determine Context
+### Step 3: Determine Context
 - **New feature**: No active work, ready to start fresh
 - **Continuing work**: In-progress issues found, resume where left off
 - **Review needed**: Work marked complete, needs review/merge
 
-## Example Output
-
-```
-✓ Project Health: 3 open, 1 in-progress, 12 completed
-
-Active Work:
-  - forge-ctc: Clean up stale workflow refs (in_progress)
-    3/7 tasks done | Last: Validation logic (def5678)
-    → bd show forge-ctc for full context
-
-Recent Completions:
-  - forge-uto: Sync AGENTS.md with agent cleanup (closed 2 days ago)
-  - forge-abc: Auth refresh tokens (closed 5 days ago)
-
-Context: Continuing work
-
-Next: Resume with /dev or /validate (check issue status)
-```
-
 ## Next Steps
 
 - **If starting new work**: Run `/plan <feature-name>`

package/.opencode/commands/validate.md

@@ -2,6 +2,11 @@
 description: Complete validation (type/lint/tests/security)
 ---
 
+> **Note:** Three things share the "validate" name in Forge:
+> - `/validate` (this command): Workflow Stage 3 — rebases onto the base branch, then runs type/lint/test/security checks
+> - `forge-preflight` (formerly forge-validate): CLI tool — checks prerequisites before a stage
+> - `bun run check` (scripts/validate.sh): Local quality gate — runs type/lint/test/security checks only (does NOT rebase; assumes branch is already current with the base branch)
+
 Run comprehensive validation including type checking, linting, code review, security review, and tests.
 
 # Validate
@@ -14,10 +19,50 @@ This command validates all code before creating a pull request.
 /validate
 ```
 
-Or use the unified validation script:
+Or use the validation script (checks only — no rebase):
 
 ```bash
-bun run check    # Runs all validation steps automatically (check is the npm script name; /validate is the workflow command)
+bun run check    # Runs lint/test/security checks only. Does NOT rebase onto the base branch.
+                 # Use /validate for the full workflow (rebase + checks).
+```
+
+```
+<HARD-GATE: /validate entry — rebase onto latest base branch>
+Before running ANY validation checks:
+
+0. Resolve the base branch dynamically (do NOT hardcode master or main):
+   BASE=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
+   if [ -z "$BASE" ] || [ "$BASE" = "(unknown)" ]; then BASE="master"; fi
+
+   This handles repos using main, master, or any other default branch.
+   Falls back to "master" when HEAD is unresolved (detached remote, empty repo).
+
+1. Fetch latest base branch:
+   git fetch origin "$BASE" || { echo "✗ Fetch failed — cannot verify branch freshness"; exit 1; }
+
+   The `|| { ...; exit 1; }` guard ensures fetch failures are never silently skipped.
+
+2. Check if branch is behind:
+   BEHIND=$(git rev-list --count HEAD..origin/"$BASE")
+
+3. If BEHIND > 0:
+   a. Run: git rebase origin/"$BASE" || REBASE_FAILED=1
+   b. If rebase succeeds (REBASE_FAILED unset): print "✓ Rebased onto latest $BASE ($BEHIND commits integrated)"
+   c. If rebase fails (REBASE_FAILED=1 — conflicts or any other error):
+      - Capture conflicting files BEFORE aborting: git diff --name-only --diff-filter=U
+      - Run: git rebase --abort
+      - Print the captured conflicting file list
+      - Print: "✗ Rebase conflict — resolve manually, then re-run /validate"
+      - STOP. Do NOT proceed to any validation checks.
+
+4. If BEHIND = 0:
+   Print "✓ Branch is up-to-date with $BASE" and continue.
+
+Rationale: Without this step, validation checks run against stale code that doesn't
+include recent base branch changes. Integration issues are only caught after the PR is
+created, wasting CI cycles and review time. Rebasing here ensures /validate results
+reflect the true state of what will be merged.
+</HARD-GATE>
 ```
 
 ## What This Command Does

package/.roo/commands/dev.md

@@ -64,6 +64,32 @@ Do NOT write any code until ALL confirmed:
 
 ---
 
+
+### Multi-developer conflict check (soft block)
+
+Before starting the per-task loop, check for cross-developer conflicts:
+
+```bash
+# Auto-sync to get latest team state
+bash scripts/sync-utils.sh auto-sync
+
+# Check for conflicts with the current beads issue
+bash scripts/conflict-detect.sh --issue <beads-id>
+```
+
+If exit code 2 (validation error): show error message, abort — do not show conflict prompt.
+
+If exit code 1 (conflicts found):
+- Display the conflict output to the developer
+- Ask: "Other developers are working in overlapping areas. Proceed anyway? (y/n)"
+- If `n`: exit cleanly, no side effects
+- If `y`: log override via `bd comments add <id> "Conflict override: proceeding despite overlap with <conflicting-issues>"`, then continue to Per-Task Loop
+- Audit: record conflict override per OWASP A09
+
+If exit code 0: proceed silently to Per-Task Loop.
+
+---
+
 ## Per-Task Loop
 
 Repeat for each task in the task list, in order:

package/.roo/commands/plan.md

@@ -24,7 +24,13 @@ Before ANY planning work begins:
    a. bd worktree create .worktrees/<slug> --branch feat/<slug>
    b. cd .worktrees/<slug>
 4. Confirm: "Working in isolated worktree: .worktrees/<slug> (branch: feat/<slug>)"
-5. ONLY THEN begin Phase 1.
+5. Create the epic issue and record the stage transition:
+   ```bash
+   bd create --title="<feature-name>" --type=epic
+   bd update <id> --status=in_progress
+   bash scripts/beads-context.sh stage-transition <id> none plan
+   ```
+6. ONLY THEN begin Phase 1.
 
 Rationale: Planning commits (design docs, task lists) belong only to this feature's branch.
 If planning runs in the main directory on a non-master branch, those commits contaminate
@@ -45,6 +51,32 @@ between parallel features or sessions.
 
 ---
 
+
+### Multi-developer conflict check (soft block)
+
+Before proceeding to Phase 1, check for cross-developer conflicts:
+
+```bash
+# Auto-sync to get latest team state
+bash scripts/sync-utils.sh auto-sync
+
+# Check for conflicts with this issue's planned work area
+bash scripts/conflict-detect.sh --issue <beads-id>
+```
+
+If exit code 2 (validation error): show error message, abort — do not show conflict prompt.
+
+If exit code 1 (conflicts found):
+- Display the conflict output to the developer
+- Ask: "Other developers are working in overlapping areas. Proceed anyway? (y/n)"
+- If `n`: exit cleanly, no side effects
+- If `y`: log override via `bd comments add <id> "Conflict override: proceeding despite overlap with <conflicting-issues>"`, then continue to Phase 1
+- Audit: record conflict override per OWASP A09
+
+If exit code 0: proceed silently to Phase 1.
+
+---
+
 ## Phase 1: Design Intent (Brainstorming)
 
 **Goal**: Capture WHAT to build — purpose, constraints, success criteria, edge cases, approach.
@@ -182,6 +214,11 @@ Do NOT begin Phase 2 (web research) until:
 
 **Goal**: Find HOW to build it — best practices, known issues, security risks, TDD scenarios.
 
+Record the phase transition before starting research:
+```bash
+bash scripts/beads-context.sh stage-transition <id> plan research
+```
+
 Run these in parallel:
 
 ### Web research (parallel-deep-research skill)
@@ -272,13 +309,19 @@ Do NOT begin Phase 3 (setup) until:
 
 ## Phase 3: Setup + Task List
 
-**Goal**: Create branch, worktree, Beads issue, and a complete task list ready for /dev.
+**Goal**: Create branch, worktree, and a complete task list ready for /dev.
+
+Record the phase transition before starting setup:
+```bash
+bash scripts/beads-context.sh stage-transition <id> research setup
+```
+
+### Step 1: Link child issues to the epic
 
-### Step 1: Beads issue
+The epic was created in the Entry HARD-GATE (Phase 1 entry). If this feature requires child issues (sub-tasks tracked separately), create them now and link to the epic:
 
 ```bash
-bd create --title="<feature-name>" --type=feature
-bd update <id> --status=in_progress
+bd create --title="<sub-task-name>" --type=feature --parent=<epic-id>
 ```
 
 ### Step 2: Branch + worktree

package/.roo/commands/premerge.md

@@ -83,9 +83,6 @@ Check each of the following and update if the feature affects it. Be selective
 **F. `AGENTS.md`** (if agent config, skills, or cross-agent workflow changed):
 - Update relevant sections describing agent capabilities or workflow
 
-**G. `docs/WORKFLOW.md`** (if the workflow itself changed):
-- Update stage descriptions or workflow tables
-
 **Commit doc updates to feature branch**:
 
 ```bash

package/.roo/commands/rollback.md

@@ -187,18 +187,18 @@ git commit -m "Rollback: <files>"
 ```bash
 bunx forge rollback
 # Select: 4. Rollback specific files
-# Enter: AGENTS.md,docs/WORKFLOW.md
+# Enter: AGENTS.md,CLAUDE.md
 
 ✓ Validating file paths...
 ✓ Working directory is clean
 ✓ Extracting USER sections...
-✓ Executing: git checkout HEAD~1 -- AGENTS.md docs/WORKFLOW.md
+✓ Executing: git checkout HEAD~1 -- AGENTS.md CLAUDE.md
 ✓ Committing changes...
 ✓ Restoring USER sections...
 ✓ Amended commit to preserve USER content
 
 Rollback complete!
-  Commit: q4r5s6t "Rollback: AGENTS.md, docs/WORKFLOW.md"
+  Commit: q4r5s6t "Rollback: AGENTS.md, CLAUDE.md"
   Files affected: 2
 ```
 
@@ -718,5 +718,5 @@ bunx forge rollback
 
 - [/dev](.claude/commands/dev.md) - TDD development workflow
 - [/validate](.claude/commands/validate.md) - Validation before shipping
-- [docs/WORKFLOW.md](../../docs/WORKFLOW.md) - Complete workflow guide
+- [AGENTS.md](../../AGENTS.md) - Complete workflow guide
 - [Beads](https://github.com/beadshq/beads) - Issue tracking integration

package/.roo/commands/ship.md

@@ -30,60 +30,97 @@ Do NOT create PR until:
 ### Step 1: Verify /validate Passed
 Ensure all four validation checks completed successfully with fresh output in this session.
 
-### Step 2: Update Beads
+### Step 2: Freshness Check — Is Branch Still Current?
+
+Even though /validate rebased onto the base branch, time may have passed since then (user reviewed design doc, took a break, etc.). This lightweight check catches staleness before pushing.
+
+```bash
+BASE=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
+if [ -z "$BASE" ] || [ "$BASE" = "(unknown)" ]; then BASE="master"; fi
+git fetch origin "$BASE" || { echo "✗ Fetch failed — cannot verify freshness"; exit 1; }
+BEHIND=$(git rev-list --count HEAD..origin/"$BASE")
+```
+
+- If `BEHIND > 0`: **STOP**. Print: "$BASE has advanced since /validate ($BEHIND new commits). Run /validate again to rebase and re-check."
+- If `BEHIND = 0`: Continue to push.
+- If fetch fails: the `|| { ...; exit 1; }` guard catches this — **STOP**. Do NOT push without confirming freshness.
+
+This is NOT a full rebase — just a check. The rebase happens in /validate where the full test suite runs afterward.
+
+### Step 3: Update Beads
 ```bash
 bd update <id> --status done
 bd sync
 ```
 
-### Step 3: Push Branch
+### Step 4: Push Branch
+
+Use `--force-with-lease` because `/validate` may have rebased the branch, rewriting history. This is safe: it only forces the push if the remote branch hasn't been updated by someone else since the last fetch.
+
 ```bash
-git push -u origin <branch-name>
+git push --force-with-lease -u origin <branch-name>
 ```
 
-### Step 4: Create PR
+### Step 5: Create PR
+
+Use the narrative PR template below. Lead with WHY (Problem/Root Cause/Fix/Value) — this is what reviewers need to understand first. Keep implementation details (test coverage, security review, design doc) in a collapsible section so they're available but don't clutter the summary.
+
+If no Beads issue exists (hotfix, external contribution), skip the "Closes" line.
 
 ```bash
-gh pr create --title "feat: <feature-name>" --body "$(cat <<'EOF'
-## Summary
-[Auto-generated from commits and design doc]
+gh pr create --title "<type>: <concise description>" --body "$(cat <<'EOF'
+## Problem
+[What was broken, what need existed, or what user pain this addresses]
 
-## Design Doc
-See: docs/plans/YYYY-MM-DD-<slug>-design.md
+## Root Cause
+[Why it happened, why it was missing, or what gap existed]
 
-## Decisions Log
-See: docs/plans/YYYY-MM-DD-<slug>-decisions.md (if any undocumented decisions arose during /dev)
+## Fix
+[What this PR does to solve it — approach, not implementation details]
+
+## Value
+[Who benefits, what improves, what risk is removed]
 
-## Beads Issue
+## Beads
 Closes: <issue-id>
 
-## Key Decisions
-[From design doc - 3-5 key decisions with reasoning]
+<details>
+<summary>Implementation Details</summary>
 
-## TDD Test Coverage
-- Unit tests: [count] tests, [X] scenarios
-- Integration tests: [count] tests
-- E2E tests: [count] tests
-- All tests passing ✓
+### Test Coverage
+- Tests: [count] passing
+- Scenarios covered: [list key scenarios]
 
-## Security Review
-- OWASP Top 10: All mitigations implemented
-- Security tests: [count] scenarios passing
-- Automated scan: No vulnerabilities
+### Security Review
+- OWASP Top 10: [summary — applicable risks and mitigations]
+- Automated scan: [result]
 
-## Test Plan
+### Design Doc
+See: docs/plans/YYYY-MM-DD-<slug>-design.md
+
+### Decisions Log
+See: docs/plans/YYYY-MM-DD-<slug>-decisions.md (if any undocumented decisions arose during /dev)
+
+### Key Decisions
+[From design doc — 3-5 key decisions with reasoning]
+
+### Documentation Updated
+[List docs updated in this PR, or "None — no doc-facing changes"]
+
+### Validation
 - [x] Type check passing
-- [x] Lint passing
-- [x] Code review passing
-- [x] E2E tests passing
+- [x] Lint passing (0 errors, 0 warnings)
+- [x] All tests passing
 - [x] Security review completed
 
+</details>
+
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 EOF
 )"
 ```
 
-### Step 5: Record Stage Transition
+### Step 6: Record Stage Transition
 ```bash
 bash scripts/beads-context.sh stage-transition <id> ship review
 ```
@@ -92,20 +129,13 @@ bash scripts/beads-context.sh stage-transition <id> ship review
 
 ```
 ✓ Validation: /validate passed (all 4 checks — fresh output confirmed)
+✓ Freshness: Branch is up-to-date with master
 ✓ Beads: Marked done & synced (forge-xyz)
 ✓ Pushed: feat/stripe-billing
 ✓ PR created: https://github.com/.../pull/123
+  - PR body: Problem → Root Cause → Fix → Value (narrative format)
   - Beads linked: forge-xyz
-  - Design doc linked: docs/plans/2026-02-26-stripe-billing-design.md
-  - Decisions log linked: docs/plans/2026-02-26-stripe-billing-decisions.md
-  - Test coverage documented
-  - Security review documented
-
-PR Summary:
-  - 12 commits
-  - 18 test cases, all passing
-  - OWASP Top 10 security review completed
-  - 3 key architectural decisions documented
+  - Implementation details in collapsible section
 
 ⏸️  PR created, awaiting automated checks (Greptile, SonarCloud, GitHub Actions)
 
@@ -127,9 +157,9 @@ Stage 7: /verify     → Post-merge CI check on main
 
 ## Tips
 
-- **Complete PR body**: Include design doc, decisions log, and test coverage
-- **Link everything**: Design doc, decisions log, Beads issue
-- **Document security**: OWASP Top 10 review in PR body
+- **Lead with why**: Problem → Root Cause → Fix → Value is what reviewers need first
+- **Collapsible details**: Design doc, decisions log, test coverage go in `<details>` — available but not in the way
+- **Document security**: OWASP Top 10 review in collapsible section
 - **Test coverage**: Show all test scenarios passing
 - **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
 - **NO auto-merge**: Always wait for /review phase

package/.roo/commands/status.md

@@ -17,60 +17,31 @@ This command helps you understand the current state of the project before starti
 
 ## What This Command Does
 
-### Step 1: Check Project Health
-```bash
-bd stats
-```
-- How many open / in-progress / completed issues?
-- Any blocked issues?
+## Step 0: Sync team state
 
-### Step 2: Check Active Work
 ```bash
-# Active Beads issues
-bd list --status in_progress
+# Sync team state before showing status
+bash scripts/sync-utils.sh auto-sync
 ```
 
-For each in-progress issue, show compact progress:
+### Step 1: Smart Status (ranked issues with conflict detection)
 ```bash
-bash scripts/beads-context.sh parse-progress <issue-id>
+bash scripts/smart-status.sh
 ```
-Display the compact output (e.g., "3/7 tasks done | Last: Validation logic (def5678)")
+This script dynamically computes and displays all issues ranked by composite score (priority, dependency impact, type, staleness, epic proximity). Output includes active sessions, conflict risk annotations, and grouped categories. No manual querying needed — the script handles everything.
 
-Hint: `bd show <id>` for full context on any issue.
+For full context on any issue: `bd show <id>`
 
-### Step 3: Review Recent Work
+### Step 2: Review Recent Commits
 ```bash
-# Recent commits
 git log --oneline -10
-
-# Recently completed Beads
-bd list --status completed --limit 5
 ```
 
-### Step 4: Determine Context
+### Step 3: Determine Context
 - **New feature**: No active work, ready to start fresh
 - **Continuing work**: In-progress issues found, resume where left off
 - **Review needed**: Work marked complete, needs review/merge
 
-## Example Output
-
-```
-✓ Project Health: 3 open, 1 in-progress, 12 completed
-
-Active Work:
-  - forge-ctc: Clean up stale workflow refs (in_progress)
-    3/7 tasks done | Last: Validation logic (def5678)
-    → bd show forge-ctc for full context
-
-Recent Completions:
-  - forge-uto: Sync AGENTS.md with agent cleanup (closed 2 days ago)
-  - forge-abc: Auth refresh tokens (closed 5 days ago)
-
-Context: Continuing work
-
-Next: Resume with /dev or /validate (check issue status)
-```
-
 ## Next Steps
 
 - **If starting new work**: Run `/plan <feature-name>`

package/.roo/commands/validate.md

@@ -3,6 +3,11 @@ description: Complete validation (type/lint/tests/security)
 mode: code
 ---
 
+> **Note:** Three things share the "validate" name in Forge:
+> - `/validate` (this command): Workflow Stage 3 — rebases onto the base branch, then runs type/lint/test/security checks
+> - `forge-preflight` (formerly forge-validate): CLI tool — checks prerequisites before a stage
+> - `bun run check` (scripts/validate.sh): Local quality gate — runs type/lint/test/security checks only (does NOT rebase; assumes branch is already current with the base branch)
+
 Run comprehensive validation including type checking, linting, code review, security review, and tests.
 
 # Validate
@@ -15,10 +20,50 @@ This command validates all code before creating a pull request.
 /validate
 ```
 
-Or use the unified validation script:
+Or use the validation script (checks only — no rebase):
 
 ```bash
-bun run check    # Runs all validation steps automatically (check is the npm script name; /validate is the workflow command)
+bun run check    # Runs lint/test/security checks only. Does NOT rebase onto the base branch.
+                 # Use /validate for the full workflow (rebase + checks).
+```
+
+```
+<HARD-GATE: /validate entry — rebase onto latest base branch>
+Before running ANY validation checks:
+
+0. Resolve the base branch dynamically (do NOT hardcode master or main):
+   BASE=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
+   if [ -z "$BASE" ] || [ "$BASE" = "(unknown)" ]; then BASE="master"; fi
+
+   This handles repos using main, master, or any other default branch.
+   Falls back to "master" when HEAD is unresolved (detached remote, empty repo).
+
+1. Fetch latest base branch:
+   git fetch origin "$BASE" || { echo "✗ Fetch failed — cannot verify branch freshness"; exit 1; }
+
+   The `|| { ...; exit 1; }` guard ensures fetch failures are never silently skipped.
+
+2. Check if branch is behind:
+   BEHIND=$(git rev-list --count HEAD..origin/"$BASE")
+
+3. If BEHIND > 0:
+   a. Run: git rebase origin/"$BASE" || REBASE_FAILED=1
+   b. If rebase succeeds (REBASE_FAILED unset): print "✓ Rebased onto latest $BASE ($BEHIND commits integrated)"
+   c. If rebase fails (REBASE_FAILED=1 — conflicts or any other error):
+      - Capture conflicting files BEFORE aborting: git diff --name-only --diff-filter=U
+      - Run: git rebase --abort
+      - Print the captured conflicting file list
+      - Print: "✗ Rebase conflict — resolve manually, then re-run /validate"
+      - STOP. Do NOT proceed to any validation checks.
+
+4. If BEHIND = 0:
+   Print "✓ Branch is up-to-date with $BASE" and continue.
+
+Rationale: Without this step, validation checks run against stale code that doesn't
+include recent base branch changes. Integration issues are only caught after the PR is
+created, wasting CI cycles and review time. Rebasing here ensures /validate results
+reflect the true state of what will be merged.
+</HARD-GATE>
 ```
 
 ## What This Command Does

package/AGENTS.md

@@ -71,6 +71,10 @@ When the user requests work, **you MUST automatically classify** the change type
 
  Proceed?"
 
+**Dynamic commands — no hardcoded examples:**
+
+Command files (`.claude/commands/*.md` and agent equivalents) must never hardcode example output when a script generates that output dynamically. Reference the script and describe what it does — don't duplicate its output with fake data that becomes stale.
+
 ## TDD Development (Stage 2: /dev)
 
 **Subagent-driven per-task implementation loop:**
@@ -108,6 +112,8 @@ Task 2: Validation logic
 
 ## State Management (Single Source of Truth)
 
+> GitHub issue lifecycle may sync to Beads via CI -- see [docs/BEADS_GITHUB_SYNC.md](docs/BEADS_GITHUB_SYNC.md).
+
 **All workflow state stored in Beads metadata** (survives compaction):
 
 ```json
@@ -162,7 +168,7 @@ Task 2: Validation logic
 - `docs/plans/YYYY-MM-DD-<slug>-decisions.md` - Decisions log from /dev
 
 **Comprehensive workflow guide:**
-- [docs/WORKFLOW.md](docs/WORKFLOW.md) - Complete workflow documentation (150 lines)
+- This file (AGENTS.md) is the single source of truth for the complete workflow
 - [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) - Tool setup and configuration
 - [docs/VALIDATION.md](docs/VALIDATION.md) - Enforcement and validation details
 

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Project Instructions
 
-This is a [describe what this project does in one sentence].
+Forge is a 7-stage TDD-first development workflow harness for AI coding agents (9 commands total, including utility stages).
 
 **Package manager**: Bun (preferred for performance)
 
@@ -72,13 +72,13 @@ This project uses the **Professional Git Workflow** with Lefthook for automated
 - **All review comments must be resolved** before merge
 - Squash-only merging: Clean, linear git history
 
-**Emergency bypass**:
+**Emergency bypass** (human-only, NEVER for AI agents):
 ```bash
 LEFTHOOK=0 git push              # Skip all pre-push hooks
 git commit --no-verify           # Skip pre-commit hooks
 ```
 
-**⚠️ Only use bypasses for emergencies.** Document reason in PR description.
+**⚠️ AI agents must NEVER use `LEFTHOOK=0`, `--no-verify`, or any hook bypass.** If a hook fails, fix the underlying issue. Only humans may bypass hooks in emergencies, documented in the PR description.
 
 See [.github/pull_request_template.md](.github/pull_request_template.md) for PR guidelines.
 
@@ -93,7 +93,8 @@ As you work, when you give the same instruction twice, add it here:
 - **Scope discipline**: Do ONLY what was explicitly asked. Answer a question → stop. Check something → stop. Never auto-continue to next steps or pending work unless told to.
 - **Stage names**: The validation stage is `/validate` (not `/check`) — renamed in PR #50.
 - **Unused params**: Prefix with `_` (e.g., `_searchTerm`) — ESLint `no-unused-vars` enforced with `--max-warnings 0`.
-- **Pre-push test env**: `test-env/` fixture tests can fail during actual `git push` due to git mid-push state; `LEFTHOOK=0 git push` is the bypass when manual `bun test` confirms 0 fail.
+- **Pre-push test env**: `test-env/` fixture tests can fail during actual `git push` due to git mid-push state. Fix the root cause — never use `LEFTHOOK=0`.
 - **Command sync**: After editing `.claude/commands/*.md`, run `node scripts/sync-commands.js` to update all 7 agent directories. Use `--check` in CI to detect drift. Use `--dry-run` to preview.
+- **Dynamic commands**: Never hardcode example output in command files (`.claude/commands/*.md`) when a script generates that output dynamically. Command files should reference the script and describe what it does — not duplicate its output with fake data that becomes stale.
 
 <!-- USER:END -->