@DevForgeAI.md

# CLAUDE.md — DevForgeAI2 Project

Project-specific guidance for the **DevForgeAI** framework's own development repository.
Framework-wide steering lives in `DevForgeAI.md` (auto-imported via the `@` directive above).
Detailed rules live in `.claude/rules/` (auto-loaded by Claude Code).

---

## Branch Policy

- **Integration branch:** `main` — protected by a GitHub ruleset (`main-branch-protection`, enforcement active): merges go through a PR; direct pushes, branch deletion, and force-pushes are blocked. No required-approval gate is set (solo-maintainer repo — `required_approving_review_count: 0`). The `Run Python CLI Tests` status check is required on `main` (ADR-119).
- **Working branches:** All work happens on feature branches (`feat/<topic>`, `fix/<topic>`, etc.). Never commit directly to `main` — if on `main`, switch to a feature branch before any commits.

---

## Build, Test, and Validate Commands

```bash
# JavaScript (npm) tests
npm test                    # All tests (Jest)
npm run test:unit           # Unit tests only (tests/npm-package/unit)
npm run test:integration    # Integration tests only (tests/npm-package/integration)
npm run test:coverage       # All tests with coverage report (80% threshold)

# Python CLI validator setup (one-time, installs globally — NO venv needed)
pip install -e src/claude/scripts/

# DevForgeAI CLI validator (globally installed — do NOT prefix with source/venv)
devforgeai-validate phase-init STORY-NNN --project-root=. 2>&1
devforgeai-validate validate-dod path/to/STORY-NNN.story.md 2>&1

# Test harness (PREFERRED) — language-agnostic runner, no venv activation needed
# Auto-detects pytest/jest/vitest/xUnit/NUnit/MSTest/go test/cargo test
# Resolves .venv/Scripts/python.exe internally and invokes python -m pytest
# Auto-appends --capture=no on WSL (works around pytest capture tmpfile crash)
devforgeai-validate run-tests STORY-NNN                                        # Auto-scopes to tests/STORY-NNN/, falls back to tests/
devforgeai-validate run-tests STORY-NNN --path=tests/                          # All Python tests
devforgeai-validate run-tests STORY-NNN --path=tests/path/to/test_file.py      # Single test file
devforgeai-validate run-tests STORY-NNN --coverage                             # Run with --cov=src --cov-report=term-missing
devforgeai-validate run-tests STORY-NNN --collect-only                         # List discovered tests without running (discovery)
devforgeai-validate run-tests STORY-NNN --expect-fail                          # Invert exit codes (Phase 02 Red verification)
devforgeai-validate run-tests STORY-NNN --format=json                          # Structured output for phase state tracking

# Python tests (direct pytest — fallback when harness can't be used)
# ALWAYS run against src/ tree, never operational folders
# Tests require venv; the CLI above does NOT
source .venv/bin/activate
pytest tests/                                     # All Python tests
pytest tests/path/to/test_file.py                 # Single test file
pytest tests/STORY-NNN/                           # Story-specific tests

# Pre-commit hook validation (runs automatically on git commit)
# Validates DoD items in story files — do NOT bypass with --no-verify
```

**WSL Warning:** Tests against operational `.claude/` folders historically produce corrupt/missing file errors. Always test against `src/` tree.

---

## Architecture (This Repo)

### Dual-Path File System

This repository uses a dual-path architecture — **never mix these paths**:

| Path | Purpose | Editable? |
|------|---------|-----------|
| `src/` | Source code for development and npm package distribution | Yes |
| `.claude/` | Operational runtime files (skills, agents, commands, hooks) | Yes |
| `devforgeai/specs/context/` | 6 constitutional constraint files | **Immutable** (requires ADR) |

- `src/` and `.claude/` contain mirrored content (skills, agents, commands) synced via CI.
- Development implementations go in `src/`; operational configs stay in `.claude/`.
- Never replace operational paths with `src/` paths or vice versa.

### Languages and Entry Points

| Component | Language | Entry Point |
|-----------|----------|-------------|
| CLI installer | Node.js | `bin/devforgeai.js` → `lib/cli.js` |
| Phase validator | Python | `src/claude/scripts/devforgeai_cli/` |
| Feedback system | Python | `src/claude/scripts/devforgeai_cli/feedback/` |
| Skills/Agents/Commands | Markdown | `.claude/skills/`, `.claude/agents/`, `.claude/commands/` |
| Hook scripts | Bash | `.claude/hooks/*.sh` |

**NPM dependencies (5 only):** chalk, cli-progress, commander, inquirer, ora

---

## Environment Constraints

- **WSL/Sandbox:** Cargo release builds may fail due to read-only filesystem — fall back to debug builds. Use `TMPDIR` workaround for tarpaulin/build cache issues. `cargo-audit` and network-dependent tools may be pre-installed — ask before attempting install. Never assume network access in sandbox.
- **Temporary files** (use `tmp/STORY-NNN/`, never system `/tmp/`) and **sandbox-restricted git operations** (`rebase`, `restore`, `checkout`, `reset --hard`, `pull --rebase`, `stash pop` can fail partially on protected `.claude/` paths): see `.claude/rules/workflow/operational-safety.md` Rules 2 & 4.

---

## Quick Reference

| Topic | File |
|-------|------|
| Framework steering | `DevForgeAI.md` (this repo root) |
| Framework rules index | `.claude/rules/README.md` |
| Test writing standards | `.claude/rules/workflow/test-writing-standards.md` |
| Dev workflow | `.claude/skills/spec-driven-dev/SKILL.md` |
| QA workflow | `.claude/skills/spec-driven-qa/SKILL.md` |
| Story template | `.claude/skills/spec-driven-stories/assets/templates/story-template.md` |
| Skills catalog | `.claude/skills/` |
| Commands catalog | `.claude/commands/` |
| Parallel execution patterns | `docs/guides/parallel-patterns-quick-reference.md` |
| Test harness (`run-tests`) | `src/claude/scripts/devforgeai_cli/commands/run_tests.py` |

---

## Framework Incident Policy

When you identify a defect or a missing enforcement in the **DevForgeAI framework itself** (not application code) that should be fixed so the fix reaches every project installing the framework, file a GitHub issue in `bankielewicz/DevForgeAI` as a **`bug`** (something is broken or wrong) or an **`enhancement`** (a new gate, lint, or capability). Local memory is per-machine and never reaches other consumers — a GitHub issue is the portable mechanism. Confirm with the user before filing (filing is an outward-facing action). Every incident MUST be:

- **Full-fidelity** — every claim grounded with a verified `file:line` citation (Read/Grep against live code, never from memory). State the root cause, the observable signature (the exact tool call / path / command / exit code that triggers it), and the proposed enforcement mechanism (hook / CLI gate / CI lint). No claim ships unverified. Mirrors Critical Rule 16.
- **Zero-ambiguity** — concrete reproduction, exact files, exact fix surface. No "somewhere" / "various" / "may" hedging; a reader with no prior context can act on it directly.
- **Nothing aspirational** — describe only what IS broken and what WILL be fixed. Forbidden: "should eventually", "ideally", "in the future", "nice to have", "consider". If it is not a committed, scoped change, it is not an incident.

Mechanism: `gh issue create --repo bankielewicz/DevForgeAI --label <bug|enhancement>`, or delegate to a `github-incident-from-*` skill where one applies.

---

**When in doubt → HALT → `AskUserQuestion`**
