its-magic 0.1.2-11 → 0.1.2-13

package/.cursor/commands/auto.md

@@ -10,18 +10,25 @@ description: "its-magic auto: run phases sequentially until decision gate."
 
 ## Inputs
 - `AUTO_FLOW_MODE` and `PHASE_MODE` from `.cursor/scratchpad.md`
+- `AUTO_IMPLEMENTATION_LOOP`, `AUTO_LOOP_MAX_CYCLES` from `.cursor/scratchpad.md`
+- `AUTO_PAUSE_REQUEST`, `AUTO_PAUSE_POLICY` from `.cursor/scratchpad.md`
 - Current product and engineering docs
 
 ## Outputs (artifacts)
 - Updated phase artifacts for each step
 - `docs/engineering/state.md`
 - `handoffs/resume_brief.md` if stopped
+- `sprints/S0001/qa-findings.md` and `handoffs/qa_to_dev.md` when loop finds issues
 
 ## Stop conditions
 - Decision gate triggered
 - Missing critical input
+- `AUTO_PAUSE_REQUEST=1` reached at a safe boundary
+- `AUTO_LOOP_MAX_CYCLES` reached with unresolved defects
 
 ## Steps
 1. Read automation flags from scratchpad.
 2. Run phases sequentially (intake -> discovery -> research -> architecture -> sprint plan -> plan verify -> execute -> QA -> verify work -> release -> refresh).
-3. Stop at decision gate or missing info and write resume brief.
+3. If `AUTO_IMPLEMENTATION_LOOP=1`, loop between `execute` and `QA` until QA has no blocking findings, then continue to `verify work` and `release`.
+4. If `AUTO_PAUSE_REQUEST=1`, complete the current safe boundary (`AUTO_PAUSE_POLICY`) and run `/pause` to persist checkpoint artifacts.
+5. Stop at decision gate or missing info and write resume brief.

package/.cursor/commands/execute.md

@@ -10,6 +10,7 @@ description: "its-magic execute: implement tasks with artifacts and state update
 ## Inputs
 - `sprints/S0001/tasks.md`
 - `handoffs/tl_to_dev.md`
+- Optional: `handoffs/qa_to_dev.md` when fixing QA findings
 
 ## Outputs (artifacts)
 - Code changes
@@ -29,4 +30,8 @@ description: "its-magic execute: implement tasks with artifacts and state update
    via the appropriate package manager without prompting.
 5. If `REMOTE_EXECUTION=1` and `.cursor/remote.json` is configured, use
    remote/docker servers for heavy builds or tests when needed.
+6. If `RUN_TESTS_ON_EDIT=1`, run configured tests after meaningful edits.
+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`.
 

package/.cursor/commands/pause.md

@@ -9,6 +9,7 @@ description: "its-magic pause: write checkpoint and resume brief."
 
 ## Inputs
 - Current sprint progress and state
+- Optional intent: immediate pause or graceful pause after current boundary
 
 ## Outputs (artifacts)
 - `docs/engineering/state.md`
@@ -22,4 +23,8 @@ description: "its-magic pause: write checkpoint and resume brief."
 1. Write a short checkpoint of current work.
 2. Update sprint progress and state.
 3. Write a resume brief with next actions.
+4. Record the intended resume phase in `handoffs/resume_brief.md` (for example:
+   execute, qa, verify-work, release).
+5. If this pause was requested via `AUTO_PAUSE_REQUEST=1`, reset the flag to `0`
+   after checkpoint is complete.
 

package/.cursor/commands/qa.md

@@ -24,5 +24,8 @@ description: "its-magic QA: test plan, findings, verify fixes."
 1. Define a test plan and run verification.
 2. Record findings and severity.
 3. Update state and handoff to dev if needed.
-4. Follow with `/verify-work` for user acceptance.
+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.
 

package/.cursor/commands/resume.md

@@ -12,6 +12,7 @@ description: "its-magic resume: load context pack and continue work."
 - `docs/engineering/decisions.md`
 - `sprints/S0001/summary.md`
 - `handoffs/resume_brief.md`
+- Optional automation flags from `.cursor/scratchpad.md`
 
 ## Outputs (artifacts)
 - Updated `docs/engineering/state.md` (if needed)
@@ -22,5 +23,7 @@ description: "its-magic resume: load context pack and continue work."
 ## Steps
 1. Load the context pack and open decisions.
 2. Summarize current status and next steps.
-3. Hand off to the appropriate phase.
+3. Continue from the resume phase noted in `handoffs/resume_brief.md`.
+4. If `AUTO_FLOW_MODE=auto_until_decision`, continue automation until the next
+   decision gate, pause request, or blocker.
 

package/.cursor/commands/verify-work.md

@@ -23,3 +23,5 @@ description: "its-magic verify work: guided user acceptance testing."
 1. Convert acceptance criteria into testable UAT steps.
 2. Record results and failures.
 3. Update state with pass/fail summary.
+4. If `AUTO_IMPLEMENTATION_LOOP=1` and UAT fails, write a handoff to dev/QA and
+   continue the fix loop within `AUTO_LOOP_MAX_CYCLES`.

package/.cursor/hooks/README.md

@@ -9,5 +9,6 @@ Events handled:
 - afterFileEdit: tracks code edits vs context refresh
 - stop: optional reminder to refresh context
 
-Behavior is controlled via `.cursor/scratchpad.md`.
+Behavior is controlled via `.cursor/scratchpad.md` with optional local overrides
+from `.cursor/scratchpad.local.md`.
 

package/.cursor/hooks/hook.py

@@ -6,14 +6,15 @@ from datetime import datetime
 
 ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
 SCRATCHPAD = os.path.join(ROOT, ".cursor", "scratchpad.md")
+SCRATCHPAD_LOCAL = os.path.join(ROOT, ".cursor", "scratchpad.local.md")
 STATE_FILE = os.path.join(ROOT, ".cursor", "hooks", "hook-state.json")
 BENCH_LOG = os.path.join(ROOT, ".cursor", "hooks", "bench-log.jsonl")
 
 
-def read_scratchpad():
+def read_kv_file(path):
     flags = {}
     try:
-        with open(SCRATCHPAD, "r", encoding="utf-8") as f:
+        with open(path, "r", encoding="utf-8") as f:
             for line in f:
                 line = line.strip()
                 if not line or line.startswith("#"):
@@ -26,6 +27,14 @@ def read_scratchpad():
     return flags
 
 
+def read_scratchpad():
+    flags = read_kv_file(SCRATCHPAD)
+    # Local overrides are optional and intentionally gitignored.
+    local = read_kv_file(SCRATCHPAD_LOCAL)
+    flags.update(local)
+    return flags
+
+
 def load_state():
     try:
         with open(STATE_FILE, "r", encoding="utf-8") as f:

package/.cursor/rules/coding-standards.mdc

@@ -0,0 +1,29 @@
+---
+description: "Strict coding standards and language best practices"
+globs: ["**/*"]
+---
+
+- Follow the official best practices of each language/framework used in the
+  changed files. Do not use deprecated APIs unless explicitly required.
+- Keep behavior deterministic and explicit: avoid hidden side effects and
+  implicit global state.
+- Prefer readability over cleverness. Use clear naming and small functions.
+- Match existing project conventions for formatting, structure, and patterns.
+- Keep interfaces stable and backward compatible unless the task requires a
+  breaking change (then document the break and migration steps).
+- Validate input boundaries and handle errors intentionally (no silent catches).
+- Never swallow exceptions without logging/context and a clear recovery path.
+- Avoid duplicated logic; extract shared behavior when repetition appears.
+- Minimize complexity: avoid unnecessary abstraction, deep nesting, and large
+  functions/classes.
+- Use strict typing and contracts where available (TypeScript/Python typing/etc).
+- No dead code, commented-out code blocks, or unused variables/imports.
+- Add or update tests for behavior changes. Tests must verify outcomes, not only
+  implementation details.
+- If tests/lint/typecheck fail for changed areas, fix before marking work done.
+- Security by default: validate untrusted input, avoid injection-prone patterns,
+  and do not introduce secrets into code or artifacts.
+- Performance by default: avoid obvious N+1 loops, repeated expensive work, and
+  unnecessary I/O in hot paths.
+- Documentation by default: update relevant docs when behavior, setup, or usage
+  changes.

package/.cursor/rules/core.mdc

@@ -10,6 +10,11 @@ globs: ["**/*"]
   decision gates (`auto_until_decision` recommended).
 - `PHASE_MODE=interactive` means ask questions; `PHASE_MODE=auto` minimizes
   prompts unless decisions are required.
+- `AUTO_IMPLEMENTATION_LOOP=1` enables an automatic fix loop:
+  execute -> QA -> execute (and verify-work) until quality gates are green or
+  `AUTO_LOOP_MAX_CYCLES` is reached.
+- `AUTO_PAUSE_REQUEST=1` requests a graceful stop at the next safe boundary
+  defined by `AUTO_PAUSE_POLICY` (`after_task` or `after_phase`).
 - Persist decisions and state in files; do not keep critical info only in chat.
 - Pause/resume is first-class. Update `handoffs/resume_brief.md` on pause.
 - Context pack must stay compact: summarize, do not dump raw logs.

package/.cursor/rules/quality.mdc

@@ -10,6 +10,9 @@ globs: ["**/*"]
 - If `AUTO_RELEASE_NOTES=1` in `.cursor/scratchpad.md`, generate release notes
   automatically (scripted).
 - If `PERMISSION_MODE=auto`, do not ask for routine permission prompts.
+- If `RUN_TESTS_ON_EDIT=1`, run configured tests after meaningful edits.
+- If `LOOP_UNTIL_GREEN=1`, iterate fix/test until green, bounded by
+  `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.
 

package/.cursor/scratchpad.local.example.md

@@ -0,0 +1,36 @@
+# its-magic scratchpad (local overrides example)
+#
+# Copy this file to `.cursor/scratchpad.local.md` and set your personal values.
+# This file is intended to stay local and is gitignored.
+#
+# Team identity / ownership
+# - TEAM_MODE: 0|1
+# - TEAM_MEMBER: short id for current developer
+# - ACTIVE_TASK_IDS: comma-separated task ids (for example T-12,T-13)
+TEAM_MODE=0
+TEAM_MEMBER=
+ACTIVE_TASK_IDS=
+#
+# Personal automation style
+# - PHASE_MODE: interactive|auto
+# - PERMISSION_MODE: interactive|auto
+# - RUN_TESTS_ON_EDIT: 0|1
+# - LOOP_UNTIL_GREEN: 0|1
+# - AUTO_IMPLEMENTATION_LOOP: 0|1
+# - AUTO_LOOP_MAX_CYCLES: integer >= 1
+# - AUTO_PAUSE_POLICY: after_task|after_phase
+PHASE_MODE=interactive
+PERMISSION_MODE=interactive
+RUN_TESTS_ON_EDIT=0
+LOOP_UNTIL_GREEN=0
+AUTO_IMPLEMENTATION_LOOP=0
+AUTO_LOOP_MAX_CYCLES=5
+AUTO_PAUSE_POLICY=after_phase
+#
+# Personal environment preferences
+# - AUTO_INSTALL_DEPS: 0|1
+# - REMOTE_EXECUTION: 0|1
+# - REMOTE_CONFIG: path to your local remote config
+AUTO_INSTALL_DEPS=0
+REMOTE_EXECUTION=0
+REMOTE_CONFIG=.cursor/remote.json

package/.cursor/scratchpad.md

@@ -1,13 +1,25 @@
 # its-magic scratchpad
 #
+# Shared team defaults live here.
+# Personal developer overrides belong in `.cursor/scratchpad.local.md`
+# (copy from `.cursor/scratchpad.local.example.md`).
+#
 # Core behavior
 # - MAGIC_CONTEXT_STRICT: 0|1 (require context refresh after code changes)
 # - LOOP_UNTIL_GREEN: 0|1 (optional test loop)
 # - RUN_TESTS_ON_EDIT: 0|1 (run tests after edits)
+# - AUTO_IMPLEMENTATION_LOOP: 0|1 (auto cycle execute->qa->execute)
+# - AUTO_LOOP_MAX_CYCLES: integer >= 1 (safety guard)
+# - AUTO_PAUSE_REQUEST: 0|1 (request graceful stop at next safe boundary)
+# - AUTO_PAUSE_POLICY: after_task|after_phase (safe stop boundary)
 # - DONE: 0|1 (stop hook loops)
 MAGIC_CONTEXT_STRICT=1
 LOOP_UNTIL_GREEN=0
 RUN_TESTS_ON_EDIT=0
+AUTO_IMPLEMENTATION_LOOP=0
+AUTO_LOOP_MAX_CYCLES=5
+AUTO_PAUSE_REQUEST=0
+AUTO_PAUSE_POLICY=after_phase
 DONE=0
 #
 # Benchmarking

package/.github/workflows/ci.yml

@@ -6,6 +6,7 @@ on:
   pull_request:
 
 jobs:
+  # ── Unit / structure tests (from runbook) ──────────────────────────
   checks:
     runs-on: ubuntu-latest
     steps:
@@ -47,3 +48,116 @@ jobs:
         if: ${{ steps.runbook.outputs.TEST_COMMAND == '' && steps.runbook.outputs.LINT_COMMAND == '' && steps.runbook.outputs.TYPECHECK_COMMAND == '' }}
         run: echo "No runbook commands set."
 
+  # ── npm package test (Ubuntu) ──────────────────────────────────────
+  npm-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: npm pack
+        run: |
+          npm pack
+          TGZ=$(ls -t its-magic-*.tgz 2>/dev/null | head -1)
+          echo "TGZ=$TGZ" >> "$GITHUB_ENV"
+          echo "Package created: $TGZ"
+      - name: Install globally from tarball
+        run: npm install -g "$TGZ"
+      - name: Smoke test - help
+        run: its-magic --help
+      - name: Smoke test - install into temp dir
+        run: |
+          TEST_DIR=$(mktemp -d)
+          its-magic --target "$TEST_DIR" --mode missing --create
+          FAIL=0
+          for f in \
+            ".cursor/commands/intake.md" \
+            ".cursor/rules/core.mdc" \
+            ".cursor/hooks.json" \
+            ".cursor/scratchpad.md" \
+            "docs/engineering/runbook.md"; do
+            if [ -f "$TEST_DIR/$f" ]; then
+              echo "PASS: $f"
+            else
+              echo "FAIL: $f"
+              FAIL=1
+            fi
+          done
+          rm -rf "$TEST_DIR"
+          exit $FAIL
+      - name: Cleanup
+        if: always()
+        run: npm uninstall -g its-magic || true
+
+  # ── Homebrew formula test (macOS) ──────────────────────────────────
+  brew-test:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate formula syntax
+        run: brew style packaging/homebrew/its-magic.rb || true
+      - name: Test installer.sh
+        run: |
+          TEST_DIR=$(mktemp -d)
+          sh installer.sh --target "$TEST_DIR" --mode missing --create
+          FAIL=0
+          for f in \
+            ".cursor/commands/intake.md" \
+            ".cursor/rules/core.mdc" \
+            ".cursor/hooks.json" \
+            ".cursor/scratchpad.md" \
+            "docs/engineering/runbook.md"; do
+            if [ -f "$TEST_DIR/$f" ]; then
+              echo "PASS: $f"
+            else
+              echo "FAIL: $f"
+              FAIL=1
+            fi
+          done
+          rm -rf "$TEST_DIR"
+          exit $FAIL
+
+  # ── Chocolatey package test (Windows) ──────────────────────────────
+  choco-test:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate choco pack
+        shell: powershell
+        run: |
+          Push-Location packaging/chocolatey
+          choco pack
+          $nupkg = Get-ChildItem -Filter "*.nupkg" | Select-Object -First 1
+          if ($nupkg) {
+            Write-Host "PASS: Package created - $($nupkg.Name)"
+          } else {
+            Write-Host "FAIL: No .nupkg created"
+            exit 1
+          }
+          Pop-Location
+      - name: Test installer.ps1
+        shell: powershell
+        run: |
+          $testDir = Join-Path $env:TEMP "its-magic-ci-test"
+          & .\installer.ps1 -Target $testDir -Mode missing -Create
+          $fail = 0
+          $files = @(
+            ".cursor\commands\intake.md",
+            ".cursor\rules\core.mdc",
+            ".cursor\hooks.json",
+            ".cursor\scratchpad.md",
+            "docs\engineering\runbook.md"
+          )
+          foreach ($f in $files) {
+            $fp = Join-Path $testDir $f
+            if (Test-Path $fp) {
+              Write-Host "PASS: $f"
+            } else {
+              Write-Host "FAIL: $f"
+              $fail = 1
+            }
+          }
+          Remove-Item -Recurse -Force $testDir
+          exit $fail
+