forge-orkes 0.3.7 → 0.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "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/forge/SKILL.md

@@ -29,7 +29,7 @@ Check for state files in this order:
 4. **If one milestone:** Auto-select it. Inform user: *"Resuming milestone: [{name}] — status: {current.status}, tasks: {overall_percent}%"*
 5. **If no active milestones:** Proceed to init or ask user to create one.
 6. Load the selected milestone's state file (`.forge/state/milestone-{id}.yml`)
-7. **Route based on `current.status`, NOT on `overall_percent`.** The `current.status` field is the authoritative workflow position. A milestone is only complete when `current.status` equals `complete`. Even if `overall_percent` is 100%, the milestone still needs to go through any remaining workflow steps (verifying, auditing, refactoring) before it is truly done.
+7. **Route based on `current.status`, NOT on `overall_percent`.** The `current.status` field is the authoritative workflow position. A milestone is only complete when `current.status` equals `complete`. Even if `overall_percent` is 100%, the milestone still needs to go through remaining workflow steps (verifying, reviewing) before it is truly done.
 8. Report position briefly, then **immediately route to the next skill** (see Step 3: Mandatory Auto-Routing):
    - **Workflow status** (`current.status`) — this is the primary indicator of where you are
    - Phase progress using precise terminology: "Executed" (code done, not verified), "Verified", "Pending", "In progress" — **never say "Complete" for a phase that hasn't been verified**
@@ -85,7 +85,7 @@ Match ANY:
 - Integration with external service
 - Estimated 1-8 hours of work
 
-→ Route through: `researching` → `discussing` → `planning` → `executing` → `verifying` → `auditing` → `refactoring`
+→ Route through: `researching` → `discussing` → `planning` → `executing` → `verifying` → `reviewing`
 
 ### Full Tier
 Match ANY:
@@ -96,7 +96,7 @@ Match ANY:
 - Estimated days of work
 - User says "full", "complex", "project", "milestone"
 
-→ Route through: `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `auditing` → `refactoring`
+→ Route through: `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `reviewing`
 → Add `designing` if UI work involved
 → Add `securing` if auth/data/API touched
 
@@ -140,12 +140,11 @@ This is a **briefing, not a prompt** — the user sees where they are and what's
 | `discussing` | Invoke `Skill(discussing)`, then → `planning` (or `architecting` for Full) |
 | `planning` | Invoke `Skill(planning)`, then → `executing` |
 | `executing` | Invoke `Skill(executing)`, then → `verifying` |
-| `verifying` | Invoke `Skill(verifying)`, then → `auditing` |
-| `auditing` | Invoke `Skill(auditing)`, then → `refactoring` |
-| `refactoring` | Invoke `Skill(refactoring)`, then → `complete` |
+| `verifying` | Invoke `Skill(verifying)`, then → `reviewing` |
+| `reviewing` | Invoke `Skill(reviewing)`, then → `complete` |
 | `complete` | Milestone is done. Ask user what's next. |
 
-- **Never treat a milestone as complete just because `overall_percent` is 100%.** Task completion and workflow completion are different. All planned tasks being done (100%) means execution is finished — verification, auditing, and refactoring still need to run.
+- **Never treat a milestone as complete just because `overall_percent` is 100%.** Task completion and workflow completion are different. All planned tasks being done (100%) means execution is finished — verification and reviewing still need to run.
 - Skip completed phases (phases before `current.status`)
 - Resume from current phase
 
@@ -154,7 +153,7 @@ This is a **briefing, not a prompt** — the user sees where they are and what's
 Sometimes a session ends before the executing skill advances `current.status`. On resume, detect and fix this:
 
 - **If `current.status == executing`**: Check if all phases in the roadmap have been executed (all plans completed, commits made). If YES → advance `current.status` to `verifying` in the state file, then route to verifying. If NO → route to executing for the next unexecuted phase.
-- **If `current.status == verifying`**: Check if verification report exists. If YES and it passed → advance to `auditing`. If NO → route to verifying.
+- **If `current.status == verifying`**: Check if verification report exists. If YES and it passed → advance to `reviewing`. If NO → route to verifying.
 - **General rule**: If the work for the current status is done but the status wasn't advanced (session ended mid-handoff), advance it now and route to the next skill.
 
 ### Phase Status Wording
@@ -168,7 +167,7 @@ When reporting phase progress on resume, use precise terminology to avoid confus
 | Not yet started | **"Pending"** | No work done yet |
 | Currently in progress | **"In progress"** | Partially executed |
 
-**Never say a phase is "Complete" unless it has passed through the full workflow** (executed + verified + audited). Use "Executed" for phases where code is done but verification hasn't run. This prevents users from thinking a phase is fully done when it still needs verification.
+**Never say a phase is "Complete" unless it has passed through the full workflow** (executed + verified + reviewed). Use "Executed" for phases where code is done but verification hasn't run. This prevents users from thinking a phase is fully done when it still needs verification.
 
 ### On-Demand Discussion
 
@@ -184,8 +183,7 @@ While working at any tier, if you encounter:
 | Missing validation/error handling/null checks | Auto-add, document | Rule 2 |
 | Broken import/dep/config blocking progress | Auto-fix, document | Rule 3 |
 | Need new DB table, service layer, library swap | **STOP. Ask user.** | Rule 4 |
-| After verifying passes | Run health audit before completion | `auditing` |
-| After auditing passes | Review refactoring opportunities | `refactoring` |
+| After verifying passes | Run health audit + refactoring review | `reviewing` |
 
 When uncertain → Rule 4 (ask). Never silently make architectural decisions.
 
@@ -202,7 +200,7 @@ Each phase produces persistent artifacts (state files, plans, reports, backlogs)
 Recommend clearing context at every phase boundary in Standard and Full tiers:
 
 ```
-researching → [clear] → discussing → [clear] → architecting → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → auditing → [clear] → refactoring
+researching → [clear] → discussing → [clear] → architecting → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → reviewing
 ```
 
 **Skip the recommendation when:**
@@ -233,8 +231,7 @@ Each skill ends with a standard handoff message. The pattern is:
 | architecting | ADRs in `.forge/decisions/`, data models, API contracts | planning reads decisions |
 | planning | Plans in `.forge/phases/m{M}-{N}-{name}/`, requirements.yml, roadmap.yml, context.md | executing reads plans |
 | executing | Committed code, execution summary, milestone state updated | verifying reads must_haves from plans |
-| verifying | Verification report, desire paths updated | auditing reads project.yml + source files |
-| auditing | Health report in `.forge/audits/` | refactoring reads health report + git diff |
+| verifying | Verification report, desire paths updated | reviewing reads project.yml + source files + git diff |
 
 ### Context Loading on Resume
 
@@ -243,7 +240,7 @@ When a skill starts after a context clear, it must load its required state from
 ## State Transitions
 
 ```
-not_started → [init if new] → researching → [clear] → discussing → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → auditing → [clear] → refactoring → complete
+not_started → [init if new] → researching → [clear] → discussing → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → reviewing → complete
                                                                                                     ↗ debugging (if stuck)
                                                                                           ↗ designing (if UI)
                                                                                           ↗ securing (if auth/data)

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: