forge-orkes 0.3.7 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/settings.json

@@ -1,6 +1,6 @@
 {
   "forge": {
-    "version": "0.3.1",
+    "version": "0.1.0",
     "default_tier": "standard",
     "beads_integration": false,
     "context_gates": {
@@ -17,7 +17,11 @@
       "refactor",
       "chore",
       "docs"
-    ]
+    ],
+    "verification": {
+      "auto_fix": true,
+      "max_retries": 2
+    }
   },
   "hooks": {
     "PostToolUse": [

package/template/.claude/skills/executing/SKILL.md

@@ -92,7 +92,8 @@ For each task in the plan:
 5. **Verify** using the verify step (run tests, inspect output)
 6. **Confirm** done criteria are met
 7. **Commit** atomically
-8. **Mark complete** — `TaskUpdate` the native task to `completed`
+8. **Run verification gate** — execute configured verification commands (see Verification Gate below)
+9. **Mark complete** — `TaskUpdate` the native task to `completed`
 
 ## TDD Flow (When task type="tdd")
 
@@ -127,6 +128,73 @@ feat(auth-01): implement JWT-based login
 - Include integration test for login flow
 ```
 
+## Verification Gate
+
+After each task commit, run the project's configured verification commands to catch regressions immediately. This is mechanical enforcement — not optional, not agent-directed.
+
+### Load Config
+
+Read `.forge/project.yml → verification`. If `verification.commands` is empty or missing, skip this section entirely.
+
+```yaml
+# Example from project.yml:
+verification:
+  commands:
+    - cmd: "npm run lint"
+      advisory: false
+    - cmd: "npm test"
+      advisory: false
+    - cmd: "npx tsc --noEmit"
+      advisory: true          # pre-existing failures — warn only
+  auto_fix: true
+  max_retries: 2
+```
+
+### Execution Flow
+
+For each verification command, in order:
+
+1. **Run the command** via Bash
+2. **If it passes** → move to next command
+3. **If it fails:**
+   - **Advisory command?** → Log warning: *"Advisory: `{cmd}` failed (pre-existing issue, not blocking)."* Move to next command.
+   - **Non-advisory + `auto_fix: false`?** → Log failure and continue to next task. Don't block.
+   - **Non-advisory + `auto_fix: true`?** → Enter auto-fix loop (below)
+
+### Auto-Fix Loop
+
+When a non-advisory verification command fails with `auto_fix: true`:
+
+```
+Attempt 1:
+  1. Read the command output (error messages, failing tests, lint errors)
+  2. Identify the issue — is it caused by the current task's changes?
+     - YES → fix the code, stage fixes, amend the commit
+     - NO (pre-existing) → mark this command as advisory for this session, log warning, continue
+  3. Re-run the verification command
+  4. If passes → continue to next command
+  5. If fails → attempt 2 (up to max_retries)
+
+After max_retries exhausted:
+  → Log the failure in the execution summary
+  → Continue to next task (don't block the whole plan)
+  → The verifying skill will catch persistent failures later
+```
+
+### Integration with 3-Strike Rule
+
+Verification auto-fix attempts count toward the task's 3-strike limit. If a task has already used 2 strikes on implementation issues, it gets 1 verification retry max.
+
+### What NOT to Fix in Verification
+
+- **Pre-existing failures** not caused by the current task → mark advisory
+- **Flaky tests** that pass on re-run without code changes → note in summary, don't count as a strike
+- **Unrelated warnings** (deprecation notices, non-blocking lint info) → ignore
+
+### Quick Tier
+
+Verification gates also run for Quick tier tasks (`quick-tasking` skill). After the commit, run all non-advisory verification commands once. If they fail, show the output and let the agent fix — but limit to 1 retry (Quick tier shouldn't spend time in fix loops).
+
 ## Context Engineering
 
 ### When to Spawn Fresh Agent

package/template/.claude/skills/initializing/SKILL.md

@@ -212,6 +212,67 @@ From this, auto-detect:
 - Database (from dependencies or config)
 - Project name and description (from package.json or README)
 
+### Discovery Step 1.5: Verification Command Detection
+
+Auto-detect verification commands from the project's package manifest and config:
+
+```bash
+# Node.js projects — scan package.json scripts
+Read: package.json → scripts
+
+# Look for these common script names:
+#   test, test:unit, test:integration, test:e2e
+#   lint, lint:fix, eslint
+#   typecheck, type-check, tsc, check-types
+#   check (often runs multiple checks)
+#   build (catches type errors in compiled languages)
+
+# Python projects
+Check: Makefile, tox.ini, pyproject.toml for test/lint commands
+# e.g., pytest, ruff check, mypy
+
+# Go projects
+# Standard: go test ./..., go vet ./...
+
+# Rust projects
+# Standard: cargo test, cargo clippy
+```
+
+**Auto-detection rules for Node.js (most common):**
+
+| `package.json` script | Maps to verification command |
+|----------------------|------------------------------|
+| `test` or `test:unit` | `npm test` or `npm run test:unit` |
+| `lint` | `npm run lint` |
+| `typecheck` or `type-check` or `check-types` | `npm run typecheck` (etc.) |
+| `tsc` in scripts or `typescript` in devDeps | `npx tsc --noEmit` |
+| `eslint` in devDeps but no `lint` script | `npx eslint .` |
+
+**Advisory mode detection:** After identifying commands, run each one once silently to check baseline health. Commands that fail on the current codebase (before Forge changes anything) are marked `advisory: true` — they'll run but won't block execution. This prevents Forge from being blocked by pre-existing tech debt.
+
+```yaml
+# Example auto-detected config:
+verification:
+  commands:
+    - cmd: "npm run lint"
+      advisory: false        # passes on current codebase
+    - cmd: "npm test"
+      advisory: false        # passes on current codebase
+    - cmd: "npx tsc --noEmit"
+      advisory: true         # FAILED on current codebase — pre-existing type errors
+  auto_fix: true
+  max_retries: 2
+```
+
+Present findings to user:
+
+*"I detected these verification commands from your project:*
+- *`npm run lint` — passes currently*
+- *`npm test` — passes currently*
+- *`npx tsc --noEmit` — currently failing (pre-existing type errors, will run in advisory mode)*
+
+*These will run automatically after each task to catch regressions. Want to add, remove, or adjust any?"*
+
 ### Discovery Step 2: Design System Detection
 
 ```bash
@@ -336,6 +397,24 @@ Then:
 - Skip design-system.md creation
 - Disable Article V in the constitution
 
+### Greenfield Step 2.5: Verification Commands
+
+Ask: *"What verification commands should run after each task? Common options:"*
+
+| If your stack includes... | Suggested commands |
+|--------------------------|-------------------|
+| TypeScript | `npx tsc --noEmit` |
+| ESLint / Biome | `npm run lint` |
+| Jest / Vitest / Mocha | `npm test` |
+| Python + pytest | `pytest` |
+| Python + ruff | `ruff check .` |
+| Go | `go test ./...`, `go vet ./...` |
+| Rust | `cargo test`, `cargo clippy` |
+
+Pre-fill based on the tech stack chosen in Step 1. User confirms or adjusts. Write to the `verification` section of `project.yml`.
+
+If the user doesn't want verification gates: set `verification.commands: []` — the executing skill will skip the gate entirely.
+
 ### Greenfield Step 3: Constitutional Setup
 
 Present the 9 constitutional articles grouped by domain:
@@ -363,7 +442,7 @@ Ask: *"Which of these articles apply? I'd recommend [suggest based on stack and
 
 ## Finalize Init (Both Paths)
 
-1. Write `.forge/project.yml` with all gathered/discovered info
+1. Write `.forge/project.yml` with all gathered/discovered info (including `verification` section with detected/configured commands)
 2. Write `.forge/constitution.md` with selected articles
 3. Write `.forge/design-system.md` (if design system configured)
 4. Initialize milestone-aware state:

package/template/.forge/templates/project.yml

@@ -30,6 +30,17 @@ constraints:
     - ""                            # e.g., "No custom auth — use Clerk"
     - ""                            # e.g., "No server-side rendering"
 
+verification:
+  commands:                           # Shell commands run after each task commit
+    - ""                              # e.g., "npm run lint"
+    - ""                              # e.g., "npm test"
+    - ""                              # e.g., "npx tsc --noEmit"
+  auto_fix: true                      # On failure, agent fixes and retries
+  max_retries: 2                      # Max auto-fix attempts per command (0 = fail immediately)
+  # Commands are auto-detected during init from package.json scripts.
+  # Advisory mode: commands that were already failing before Forge started
+  # run but don't block — they log warnings only.
+
 success_criteria:                   # How do we know we're done?
   - ""                              # e.g., "User can create and edit posts"
   - ""                              # e.g., "All tests pass with >80% coverage"

package/template/CLAUDE.md

@@ -115,7 +115,7 @@ For Quick tier tasks, init is skipped — just do the work.
 ## State Management
 
 Project state lives in `.forge/`:
-- `project.yml` — Vision, stack, design system, constraints (< 5 KB)
+- `project.yml` — Vision, stack, design system, verification commands, constraints (< 5 KB)
 - `constitution.md` — Active architectural gates (selected during init)
 - `design-system.md` — Component mapping table (generated during init)
 - `requirements.yml` — Structured requirements with `[NEEDS CLARIFICATION]` markers
@@ -146,6 +146,27 @@ When the executor encounters issues during building:
 
 Priority: Rule 4 first (stop if architectural). Then Rules 1-3 (auto-fix). Uncertain? → Rule 4 (ask).
 
+## Verification Gates
+
+After each task commit, the executor runs configured verification commands from `project.yml`:
+
+```yaml
+verification:
+  commands:
+    - cmd: "npm run lint"
+    - cmd: "npm test"
+    - cmd: "npx tsc --noEmit"
+      advisory: true           # pre-existing failures — warn only
+  auto_fix: true               # agent fixes and retries on failure
+  max_retries: 2               # max auto-fix attempts per command
+```
+
+- **Auto-detected during init** from `package.json` scripts (test, lint, typecheck)
+- **Advisory mode**: commands that were already failing before Forge started run but don't block
+- **Auto-fix loop**: on failure, agent reads output, fixes code, amends commit, re-runs (up to max_retries)
+- **3-strike integration**: verification retries count toward the task's 3-strike limit
+- Empty `commands` list = no verification gate (opt-out)
+
 ## Beads Integration (Optional)
 
 When Beads is installed, Forge gains persistent cross-session memory: