its-magic 0.1.2-15 → 0.1.2-16

package/README.md

@@ -15,6 +15,7 @@ with pause/resume, decision gates, and persistent artifacts.
 - Decision gate + escalation (`decisions/DEC-xxxx.md`).
 - Pause/resume with checkpoints (`handoffs/resume_brief.md`).
 - Automated execute/QA loop with safety caps (optional).
+- 3-layer quality chain: AI loop → local validate-and-push → CI auto-fix.
 - CI/CD templates driven by `docs/engineering/runbook.md`.
 - Team-friendly local overrides (`scratchpad.local.md`).
 - Optional remote/docker execution and autonomous installs.
@@ -123,18 +124,20 @@ its-magic --clean-repo --target .
 
 ```text
 your-project/
-  .cursor/commands
-  .cursor/rules
-  .cursor/agents
-  .cursor/skills
-  .cursor/hooks
-  .cursor/scratchpad.md
+  .cursor/commands/          Cursor slash commands
+  .cursor/rules/             AI behavior rules
+  .cursor/agents/            Subagent definitions
+  .cursor/skills/            Reusable skills
+  .cursor/hooks/             Automation hooks
+  .cursor/scratchpad.md      Shared configuration flags
   .cursor/scratchpad.local.example.md
-  docs/
-  sprints/
-  handoffs/
-  decisions/
-  .github/workflows/
+  docs/                      Engineering & product docs, runbook
+  sprints/                   Sprint tracking artifacts
+  handoffs/                  Phase handoff artifacts
+  decisions/                 Decision records
+  scripts/validate-and-push.ps1   Local test-fix-push loop (Windows)
+  scripts/validate-and-push.sh    Local test-fix-push loop (Linux/Mac)
+  .github/workflows/         CI with auto-fix loop
   README.md
 ```
 
@@ -320,6 +323,108 @@ Graceful stop (for shutdown/end of day):
   - `AUTO_INSTALL_DEPS=0`
   - `AUTO_PAUSE_POLICY=after_task`
 
+### Quality chain (3-layer auto-fix)
+
+its-magic provides a complete quality chain that catches issues at three levels.
+Each layer catches problems the previous layer missed:
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│ Layer 1: Cursor AI loop (in-editor)              OFF by default │
+│   AUTO_IMPLEMENTATION_LOOP + LOOP_UNTIL_GREEN                   │
+│   execute → QA → fix → execute (bounded by AUTO_LOOP_MAX_CYCLES)│
+└──────────────────────────┬──────────────────────────────────────┘
+                           │ code ready to push
+┌──────────────────────────▼──────────────────────────────────────┐
+│ Layer 2: validate-and-push (local pre-push)      MANUAL (run it)│
+│   scripts/validate-and-push.sh / .ps1                           │
+│   test → format → lint-fix → test → commit + push               │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │ pushed to GitHub
+┌──────────────────────────▼──────────────────────────────────────┐
+│ Layer 3: CI auto-fix (GitHub Actions)            OFF by default │
+│   .github/workflows/ci.yml                                      │
+│   test/lint → auto-fix → commit → re-run (up to 3 retries)     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+| Layer | Default | Enable |
+|-------|---------|--------|
+| 1 - Cursor AI loop | off | Set `AUTO_IMPLEMENTATION_LOOP=1` + `LOOP_UNTIL_GREEN=1` in scratchpad |
+| 2 - validate-and-push | manual | Run `scripts/validate-and-push.sh` or `.ps1` before pushing |
+| 3 - CI auto-fix | off | Set `CI_AUTO_FIX: true` in `docs/engineering/runbook.md` |
+
+CI itself (tests, lint, typecheck) always runs on push/PR. Only the **auto-fix
+retry loop** is gated behind `CI_AUTO_FIX`. When disabled, CI still reports
+failures -- it just won't try to fix and commit automatically.
+
+All commands are read from `docs/engineering/runbook.md`. Fill in your
+project-specific commands once and every layer uses them:
+
+```text
+TEST_COMMAND: npm test
+LINT_COMMAND: npx eslint .
+LINT_FIX_COMMAND: npx eslint --fix .
+FORMAT_COMMAND: npx prettier --write .
+CI_AUTO_FIX: true
+```
+
+#### Layer 1: Cursor AI loop
+
+Enabled via scratchpad flags (see [Automation modes](#automation-modes)).
+The AI runs execute → QA → fix cycles inside Cursor until tests pass or
+the safety cap (`AUTO_LOOP_MAX_CYCLES`) is reached.
+
+#### Layer 2: Local validate-and-push
+
+Run before pushing to catch anything the AI loop missed:
+
+```bash
+# Bash (Linux / macOS)
+sh scripts/validate-and-push.sh
+
+# PowerShell (Windows)
+powershell scripts/validate-and-push.ps1
+powershell scripts/validate-and-push.ps1 -MaxAttempts 3
+```
+
+The script:
+1. Runs `FORMAT_COMMAND` and `LINT_FIX_COMMAND` to auto-fix what it can
+2. Runs `LINT_COMMAND` and `TEST_COMMAND` to verify
+3. If checks fail, pauses and waits for you to fix
+4. Re-runs (up to 5 attempts, configurable)
+5. When green, commits and pushes automatically
+
+Use `-NoCommit` (PowerShell) or `false` as third arg (Bash) to skip auto-push.
+
+#### Layer 3: CI auto-fix (GitHub Actions)
+
+**Disabled by default.** Set `CI_AUTO_FIX: true` in `docs/engineering/runbook.md`
+to enable. When enabled and CI fails after a push, the auto-fix job kicks in:
+
+```text
+push / PR  ──>  checks  ──>  PASS  ──>  done
+                   │
+                  FAIL
+                   │
+             auto-fix job
+                   │
+          run LINT_FIX_COMMAND
+          run FORMAT_COMMAND
+                   │
+             changes found?
+            ╱              ╲
+         yes                no
+          │                  │
+    commit + push       report failure
+          │             (manual fix needed)
+     CI re-runs
+     (up to 3x)
+```
+
+Auto-fix commits appear as `ci: auto-fix attempt N/3`. After 3 retries the
+workflow stops and points you to `scripts/validate-and-push` for local fixing.
+
 ## Examples
 
 ### Example 1: New feature from idea

package/installer.ps1

@@ -147,9 +147,13 @@ function Show-ItsMagicHelp($VersionString, $RepoUrl) {
   Write-Host ""
 }
 
-$sourceRoot = Normalize-PathSafe (Split-Path -Parent $MyInvocation.MyCommand.Path)
+$scriptDir = Normalize-PathSafe (Split-Path -Parent $MyInvocation.MyCommand.Path)
+$sourceRoot = Join-Path $scriptDir "template"
+if (-not (Test-Path $sourceRoot -PathType Container)) {
+  $sourceRoot = $scriptDir
+}
 $repoUrl = "https://github.com/fl0wm0ti0n/its-magic"
-$appVersion = Get-AppVersion $sourceRoot
+$appVersion = Get-AppVersion $scriptDir
 $noArgs = $PSBoundParameters.Count -eq 0
 
 if ($Version) {
@@ -228,6 +232,8 @@ $includePaths = @(
   "sprints",
   "handoffs",
   "decisions",
+  "scripts/validate-and-push.ps1",
+  "scripts/validate-and-push.sh",
   ".github/workflows",
   "README.md"
 )

package/installer.py

@@ -160,8 +160,10 @@ def clean_repo(target_root):
 
 
 def main():
-    source_root = normalize(os.path.dirname(__file__))
-    version = read_version(source_root)
+    script_dir = normalize(os.path.dirname(__file__))
+    template_dir = os.path.join(script_dir, "template")
+    source_root = template_dir if os.path.isdir(template_dir) else script_dir
+    version = read_version(script_dir)
 
     parser = argparse.ArgumentParser(
         description="Install its-magic into a repo",
@@ -227,6 +229,8 @@ def main():
         "sprints",
         "handoffs",
         "decisions",
+        "scripts/validate-and-push.ps1",
+        "scripts/validate-and-push.sh",
         ".github/workflows",
         "README.md",
     ]

package/installer.sh

@@ -1,9 +1,14 @@
 #!/usr/bin/env sh
 set -e
 
-SOURCE_ROOT=$(cd "$(dirname "$0")" && pwd)
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+if [ -d "$SCRIPT_DIR/template" ]; then
+  SOURCE_ROOT="$SCRIPT_DIR/template"
+else
+  SOURCE_ROOT="$SCRIPT_DIR"
+fi
 REPO_URL="https://github.com/fl0wm0ti0n/its-magic"
-APP_VERSION=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$SOURCE_ROOT/package.json" | head -n 1)
+APP_VERSION=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$SCRIPT_DIR/package.json" 2>/dev/null | head -n 1)
 [ -z "$APP_VERSION" ] && APP_VERSION="unknown"
 
 show_banner() {
@@ -228,6 +233,8 @@ docs
 sprints
 handoffs
 decisions
+scripts/validate-and-push.ps1
+scripts/validate-and-push.sh
 .github/workflows
 README.md
 "

package/package.json

@@ -1,29 +1,16 @@
 {
   "name": "its-magic",
-  "version": "0.1.2-15",
+  "version": "0.1.2-16",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {
     "its-magic": "bin/its-magic.js"
   },
   "files": [
-    ".cursor/commands/",
-    ".cursor/rules/",
-    ".cursor/skills/",
-    ".cursor/agents/",
-    ".cursor/hooks/",
-    ".cursor/hooks.json",
-    ".cursor/scratchpad.md",
-    ".cursor/scratchpad.local.example.md",
-    ".github/workflows/",
-    "decisions/",
-    "docs/",
-    "handoffs/",
-    "sprints/",
+    "template/",
     "installer.ps1",
     "installer.sh",
     "installer.py",
-    "README.md",
     "bin/its-magic.js",
     "bin/postinstall.js"
   ],

package/{.cursor → template/.cursor}/commands/execute.md

@@ -34,4 +34,6 @@ description: "its-magic execute: implement tasks with artifacts and state update
 7. If `LOOP_UNTIL_GREEN=1`, fix failing tests in small iterations until green,
    or stop and document blockers in `docs/engineering/state.md`.
 8. If `AUTO_PAUSE_REQUEST=1` and boundary rules permit, checkpoint via `/pause`.
+9. When ready to push, suggest `scripts/validate-and-push` to run the full
+   quality chain locally before CI.
 

package/{.cursor → template/.cursor}/commands/qa.md

@@ -21,11 +21,15 @@ description: "its-magic QA: test plan, findings, verify fixes."
 - Missing test plan coverage
 
 ## Steps
-1. Define a test plan and run verification.
+1. Define a test plan and run verification using the runbook commands
+   (`TEST_COMMAND`, `LINT_COMMAND`, `TYPECHECK_COMMAND` in `docs/engineering/runbook.md`).
 2. Record findings and severity.
 3. Update state and handoff to dev if needed.
 4. If `AUTO_IMPLEMENTATION_LOOP=1` and blocking issues exist, handoff to dev and
    return to `/execute` automatically (bounded by `AUTO_LOOP_MAX_CYCLES`).
 5. Follow with `/verify-work` for user acceptance when blocking issues are closed.
 6. If `AUTO_PAUSE_REQUEST=1` at safe boundary, run `/pause` before next phase.
+7. Before pushing, suggest running `scripts/validate-and-push` to catch failures
+   locally before they reach CI. If CI fails, the auto-fix job in
+   `.github/workflows/ci.yml` attempts automatic lint/format fixes and retries.
 

package/{.cursor → template/.cursor}/rules/quality.mdc

@@ -4,7 +4,8 @@ globs: ["**/*"]
 ---
 
 - Prefer small, atomic changes tied to a single task.
-- Run tests, lint, and typecheck when commands are configured.
+- Run tests, lint, and typecheck when commands are configured in
+  `docs/engineering/runbook.md` (`TEST_COMMAND`, `LINT_COMMAND`, `TYPECHECK_COMMAND`).
 - If `AUTO_INSTALL_DEPS=1` in `.cursor/scratchpad.md`, install required
   runtimes/libs without asking (package manager only).
 - If `AUTO_RELEASE_NOTES=1` in `.cursor/scratchpad.md`, generate release notes
@@ -15,4 +16,11 @@ globs: ["**/*"]
   `AUTO_LOOP_MAX_CYCLES` when set.
 - Update `docs/engineering/state.md` after meaningful changes.
 - If tests fail and commands are set, fix or document before proceeding.
+- Quality chain: Cursor AI loop (in-editor) → `scripts/validate-and-push`
+  (local pre-push) → CI auto-fix (GitHub Actions). Each layer catches issues
+  the previous layer missed.
+- Before pushing, recommend running `scripts/validate-and-push.ps1` (Windows)
+  or `scripts/validate-and-push.sh` (Linux/Mac) to catch failures locally.
+- `LINT_FIX_COMMAND` and `FORMAT_COMMAND` in the runbook enable automatic
+  formatting/lint fixes both locally and in CI.
 

package/{.github → template/.github}/workflows/ci.yml

@@ -4,13 +4,34 @@ on:
   push:
     branches: ["main"]
   pull_request:
+  workflow_dispatch:
+    inputs:
+      retry_count:
+        description: "Internal retry counter (do not set manually)"
+        required: false
+        default: "0"
+
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  MAX_CI_RETRIES: 3
 
 jobs:
   # ── Unit / structure tests (from runbook) ──────────────────────────
   checks:
     runs-on: ubuntu-latest
+    outputs:
+      test_result: ${{ steps.test.outcome }}
+      lint_result: ${{ steps.lint.outcome }}
+      ci_auto_fix: ${{ steps.runbook.outputs.CI_AUTO_FIX }}
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref || github.ref_name }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
       - id: runbook
         name: Read runbook commands
         run: |
@@ -25,7 +46,7 @@ jobs:
               if val in ("", "...", "<...>", "TODO"):
                   return ""
               return val
-          keys = ["TEST_COMMAND", "LINT_COMMAND", "TYPECHECK_COMMAND"]
+          keys = ["TEST_COMMAND", "LINT_COMMAND", "TYPECHECK_COMMAND", "CI_AUTO_FIX"]
           with open(os.environ["GITHUB_OUTPUT"], "a") as f:
               for key in keys:
                   val = get(key)
@@ -35,19 +56,134 @@ jobs:
                   else:
                       print(f"  {key} = (skipped, empty)")
           PY
+
       - name: Test
+        id: test
         if: ${{ steps.runbook.outputs.TEST_COMMAND != '' }}
+        continue-on-error: true
         run: ${{ steps.runbook.outputs.TEST_COMMAND }}
+
       - name: Lint
+        id: lint
         if: ${{ steps.runbook.outputs.LINT_COMMAND != '' }}
+        continue-on-error: true
         run: ${{ steps.runbook.outputs.LINT_COMMAND }}
+
       - name: Typecheck
+        id: typecheck
         if: ${{ steps.runbook.outputs.TYPECHECK_COMMAND != '' }}
         run: ${{ steps.runbook.outputs.TYPECHECK_COMMAND }}
+
       - name: No commands set
         if: ${{ steps.runbook.outputs.TEST_COMMAND == '' && steps.runbook.outputs.LINT_COMMAND == '' && steps.runbook.outputs.TYPECHECK_COMMAND == '' }}
         run: echo "No runbook commands set."
 
+      - name: Summarise results
+        if: always()
+        run: |
+          echo "### CI Results" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Step | Result |" >> "$GITHUB_STEP_SUMMARY"
+          echo "|------|--------|" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Test | ${{ steps.test.outcome || 'skipped' }} |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Lint | ${{ steps.lint.outcome || 'skipped' }} |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Typecheck | ${{ steps.typecheck.outcome || 'skipped' }} |" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Fail if tests or lint failed
+        if: ${{ steps.test.outcome == 'failure' || steps.lint.outcome == 'failure' }}
+        run: |
+          echo "::error::Tests or lint failed. See summary above."
+          exit 1
+
+  # ── Auto-fix attempt (runs only when checks fail) ─────────────────
+  auto-fix:
+    needs: checks
+    if: ${{ failure() && needs.checks.outputs.ci_auto_fix == 'true' && (github.event_name == 'push' || github.event_name == 'pull_request') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref || github.ref_name }}
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Determine retry count
+        id: retry
+        run: |
+          COUNT="${{ github.event.inputs.retry_count || '0' }}"
+          echo "count=$COUNT" >> "$GITHUB_OUTPUT"
+          echo "Current retry: $COUNT / ${{ env.MAX_CI_RETRIES }}"
+          if [ "$COUNT" -ge "${{ env.MAX_CI_RETRIES }}" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "::warning::Max CI retries (${{ env.MAX_CI_RETRIES }}) reached. Manual intervention required."
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Read runbook for fix commands
+        id: runbook
+        if: ${{ steps.retry.outputs.skip != 'true' }}
+        run: |
+          python3 - <<'PY'
+          import os, pathlib, re
+          text = pathlib.Path("docs/engineering/runbook.md").read_text(encoding="utf-8")
+          def get(key):
+              m = re.search(rf"^{key}:\s*(.+)$", text, re.M)
+              if not m:
+                  return ""
+              val = m.group(1).strip()
+              if val in ("", "...", "<...>", "TODO"):
+                  return ""
+              return val
+          keys = ["LINT_FIX_COMMAND", "FORMAT_COMMAND"]
+          with open(os.environ["GITHUB_OUTPUT"], "a") as f:
+              for key in keys:
+                  val = get(key)
+                  if val:
+                      f.write(f"{key}={val}\n")
+                      print(f"  {key} = '{val}'")
+                  else:
+                      print(f"  {key} = (not set)")
+          PY
+
+      - name: Run lint auto-fix
+        if: ${{ steps.retry.outputs.skip != 'true' && steps.runbook.outputs.LINT_FIX_COMMAND != '' }}
+        continue-on-error: true
+        run: ${{ steps.runbook.outputs.LINT_FIX_COMMAND }}
+
+      - name: Run formatter
+        if: ${{ steps.retry.outputs.skip != 'true' && steps.runbook.outputs.FORMAT_COMMAND != '' }}
+        continue-on-error: true
+        run: ${{ steps.runbook.outputs.FORMAT_COMMAND }}
+
+      - name: Check for changes and commit
+        if: ${{ steps.retry.outputs.skip != 'true' }}
+        id: commit
+        run: |
+          git config user.name "its-magic[bot]"
+          git config user.email "its-magic[bot]@users.noreply.github.com"
+          if git diff --quiet && git diff --cached --quiet; then
+            echo "No auto-fix changes to commit."
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          else
+            NEXT=$(( ${{ steps.retry.outputs.count }} + 1 ))
+            git add -A
+            git commit -m "ci: auto-fix attempt $NEXT/${{ env.MAX_CI_RETRIES }}"
+            git push
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+            echo "Fixes committed and pushed. CI will re-run automatically."
+          fi
+
+      - name: Post failure summary
+        if: ${{ steps.retry.outputs.skip == 'true' || steps.commit.outputs.has_changes == 'false' }}
+        run: |
+          echo "::error::CI failed and auto-fix could not resolve it."
+          echo ""
+          echo "What to do next:"
+          echo "  1. Pull the latest changes"
+          echo "  2. Run:  sh scripts/validate-and-push.sh"
+          echo "     (or:  powershell scripts/validate-and-push.ps1)"
+          echo "  3. Fix failures, the script loops until green, then pushes."
+
   # ── npm package test (Ubuntu) ──────────────────────────────────────
   npm-test:
     runs-on: ubuntu-latest
@@ -160,4 +296,3 @@ jobs:
           }
           Remove-Item -Recurse -Force $testDir
           exit $fail
-