its-magic 0.1.2-9 → 0.1.2

package/template/.cursor/commands/security-review.md

@@ -0,0 +1,81 @@
+---
+description: "its-magic security-review: optional security and compliance review."
+---
+
+# /security-review
+
+## Subagents
+- security
+
+## Execution model
+- Run `/security-review` in a fresh Security subagent context.
+- This command is guidance-driven review, not a static analysis certification.
+- After writing outputs, stop and continue the next workflow phase in a new
+  subagent/chat.
+
+## Inputs
+
+- **Narrow-read (US-0053 / US-0096 Tranche A)**: Start at docs/engineering/phase-context.md
+  and the story section anchor in vision/architecture/decisions when a heading exists; forbid
+  full-file reads when a section heading exists.
+- `SECURITY_REVIEW` and `COMPLIANCE_PROFILES` from `.cursor/scratchpad.md`
+- `docs/engineering/architecture.md`
+- `docs/engineering/decisions.md`
+- `docs/engineering/state.md`
+- Sprint tasks and implementation artifacts in code review mode
+- `handoffs/dev_to_qa.md` in code review mode (when available)
+
+## Outputs (artifacts)
+- `docs/engineering/security-review.md`
+- `decisions/DEC-xxxx.md` (critical findings only)
+- `docs/engineering/state.md`
+- `handoffs/qa_to_dev.md` (when code review finds blocking issues)
+
+## Modes
+- `design`: run after `/architecture`; focuses on architecture and control design.
+- `code`: run after `/execute`; focuses on implementation-level risk patterns.
+
+## Review scopes
+- Design review scope:
+  - architecture decisions and trust boundaries
+  - data flow/storage and sensitive-data handling
+  - authentication/authorization design
+  - third-party dependency and integration risk
+  - profile-specific requirements when configured
+- Code review scope:
+  - secrets/credentials exposure in code or config
+  - injection classes (SQL, XSS, command) and unsafe input handling
+  - authentication/authorization implementation gaps
+  - validation/sanitization/output encoding patterns
+  - profile-specific implementation requirements when configured
+
+## Stop conditions
+- `SECURITY_REVIEW=0` in scratchpad (exit immediately; no overhead)
+- Critical unresolved finding that triggers a decision gate
+- Missing mandatory review inputs for selected mode
+
+## Steps
+1. Read `SECURITY_REVIEW` and `COMPLIANCE_PROFILES` from `.cursor/scratchpad.md`.
+2. If `SECURITY_REVIEW=0`, exit with: "Security review is disabled."
+3. Determine review mode:
+   - explicit user-provided mode, or
+   - infer `design` post-architecture, `code` post-execute.
+4. Load inputs for the selected mode from artifacts and handoffs.
+5. Load compliance profile checklists:
+   - if `COMPLIANCE_PROFILES` is set, apply selected profiles (for example GDPR),
+   - if empty, apply general security best-practice baseline only.
+6. Evaluate findings against mode-specific criteria, profile guidance, and
+   severity taxonomy (`critical`, `high`, `medium`, `low`).
+7. Write findings to `docs/engineering/security-review.md` with:
+   severity, component, description, risk, remediation, and status.
+8. For each `critical` finding, enforce escalation:
+   - Create `decisions/DEC-xxxx.md` documenting vulnerability details, affected
+     components, risk assessment, and remediation options.
+   - Mark the finding as `blocking` in `docs/engineering/security-review.md`.
+   - Trigger a decision gate and pause phase progression until resolved/accepted.
+   - Resolve only through one of these documented outcomes:
+     1) fix now,
+     2) accept risk with rationale,
+     3) defer with mitigation plan and owner/timeline.
+9. Update `docs/engineering/state.md` with review mode, profile set, summary
+   counts by severity, and whether a decision gate is active.

package/template/.cursor/commands/sprint-plan.md

@@ -0,0 +1,103 @@
+---
+description: "its-magic sprint plan: create sprint and atomic tasks."
+---
+
+# /sprint-plan
+
+## Subagents
+- tech-lead
+
+## Execution model
+- Run `/sprint-plan` in a fresh Tech Lead subagent context.
+- After writing outputs, stop and hand off to `/plan-verify` in a new
+  subagent/chat.
+
+## Inputs
+
+- **Narrow-read (US-0053 / US-0096 Tranche A)**: Start at docs/engineering/phase-context.md
+  and the story section anchor in vision/architecture/decisions when a heading exists; forbid
+  full-file reads when a section heading exists.
+- Architecture and decisions
+- Current backlog priorities
+- `.cursor/scratchpad.md` — read SPRINT_MAX_TASKS and SPRINT_AUTO_SPLIT
+- Optional explicit argument: `--bulk` (US-0046)
+
+## Optional bulk mode (US-0046 / DEC-0023)
+
+`/sprint-plan` supports an explicit bulk planning mode. Default behavior remains
+single-scope unless bulk mode is explicitly requested.
+
+Bulk trigger:
+- `--bulk` argument enables deterministic multi-story planning.
+
+Bulk policy controls from `.cursor/scratchpad.md`:
+- `SPRINT_BULK_MAX_STORIES`: integer `>=1` (max candidate stories per run)
+- `SPRINT_BULK_MAX_SPRINTS`: integer `>=1` (max generated sprints per run)
+- `SPRINT_BULK_SELECTION`: `priority_then_backlog_order` (default)
+
+Bulk behavior when enabled:
+- Select eligible OPEN stories deterministically via `SPRINT_BULK_SELECTION`.
+- Generate one or more sprints until a bound is reached or no eligible stories remain.
+- Preserve sizing controls for each generated sprint (`SPRINT_MAX_TASKS`,
+  `SPRINT_AUTO_SPLIT`).
+- Emit deterministic stop reason when bounded:
+  - `SPRINT_BULK_MAX_STORIES_REACHED`
+  - `SPRINT_BULK_MAX_SPRINTS_REACHED`
+  - `SPRINT_BULK_NO_ELIGIBLE_STORIES`
+  - `SPRINT_BULK_MISSING_ACCEPTANCE`
+
+Default-safe behavior:
+- Without `--bulk`, keep existing non-bulk planning semantics.
+
+## Planning source clarification (US-0045)
+
+- Planning source of truth for story status is `docs/product/backlog.md`.
+- For multiple OPEN stories, non-bulk `/sprint-plan` selects one bounded scope
+  by current policy and sizing limits (`SPRINT_MAX_TASKS`, `SPRINT_AUTO_SPLIT`).
+- Use `/sprint-plan --bulk` for explicit multi-story planning within bounded
+  controls; do not infer additional eligibility from non-canonical status views.
+
+## Outputs (artifacts)
+- `sprints/Sxxxx/sprint.md`
+- `sprints/Sxxxx/tasks.md`
+- `sprints/Sxxxx/progress.md`
+- `handoffs/tl_to_dev.md`
+- `sprints/Sxxxx/plan-verify.json` (after /plan-verify)
+
+## Stop conditions
+- Missing acceptance criteria
+- Decision gate triggered
+- Task count exceeds SPRINT_MAX_TASKS and SPRINT_AUTO_SPLIT=1 — propose splitting before proceeding
+- Bulk limits reached when `--bulk` is enabled (`SPRINT_BULK_MAX_*`)
+
+## Steps
+1. Evaluate scope:
+   - Non-bulk mode: count expected tasks for current planning scope.
+   - Bulk mode (`--bulk`): select candidate stories deterministically
+     (`SPRINT_BULK_SELECTION`) up to `SPRINT_BULK_MAX_STORIES`.
+   Read `SPRINT_MAX_TASKS` from scratchpad (default: 12). If tasks exceed threshold
+   and `SPRINT_AUTO_SPLIT=1`, propose deterministic splitting into multiple sprints
+   or milestones. If the work is too small for a sprint, suggest `/quick` instead.
+2. Milestone activation check (DEC-0009): if this sprint belongs to a milestone, check whether this is the first sprint under that milestone. If so, transition the milestone from **created** to **active** state. Before activation, verify that `milestone.json` has real (non-placeholder) values for `name`, `goal`, and `scope`. If any are still draft/empty, populate them before proceeding. Update `phases.json` to reflect actual planned phases.
+3. For each sprint generated in this run (one in non-bulk mode, one or more in
+   bulk mode):
+   - Create sprint scope and goals.
+   - Break work into atomic tasks.
+   - Optional component-scoped planning (US-0035):
+     - If `COMPONENT_SCOPE_MODE=0`, add zero required scope metadata.
+     - If `COMPONENT_SCOPE_MODE=1`, every task must declare:
+       - `target_component_ids`
+       - `expected_impacted_interfaces`
+   - Update traceability index in `docs/engineering/state.md`: add/update one row
+     per story assigned to this sprint using DEC-0010
+     (`Story | Sprint | Tasks | Status | Evidence`). Set Status=`PLANNED`, leave
+     Evidence empty.
+   - Create UAT placeholder files per DEC-0009 lifecycle (placeholder state). For
+     `uat.json`: set sprint ID and empty steps array. For `uat.md`: list target
+     stories and acceptance criteria (no results yet).
+   - Optional user-guide (US-0032): If `USER_GUIDE_MODE=0`, add no required
+     user-guide tasks or blocking checks. If `USER_GUIDE_MODE=1`, include tasks
+     for creating/updating `docs/user-guides/US-xxxx.md` per in-scope feature story.
+4. Write TL -> Dev handoff for generated sprint set.
+5. Run `/plan-verify` to check coverage for generated sprint plan(s).
+

package/template/.cursor/commands/status-reconcile.md

@@ -0,0 +1,95 @@
+---
+description: "its-magic status-reconcile: deterministic status normalization and resume readiness."
+---
+
+# /status-reconcile
+
+## Subagents
+- curator
+- tech-lead
+
+## Execution model
+- Run `/status-reconcile` in a fresh subagent context.
+- This command performs bounded deterministic reconciliation writes.
+- Reconciliation scope is workflow artifacts only (status surfaces + resume metadata).
+- After writing outputs, stop and recommend next phase.
+
+## Inputs
+
+- **Narrow-read (US-0053 / US-0096 Tranche A)**: Start at docs/engineering/phase-context.md
+  and the story section anchor in vision/architecture/decisions when a heading exists; forbid
+  full-file reads when a section heading exists.
+- `docs/product/backlog.md` (canonical status source)
+- `docs/product/acceptance.md` (derived checklist surface)
+- `docs/engineering/state.md` (traceability + checkpoints)
+- `handoffs/resume_brief.md` (continuation intent)
+- `handoffs/release_queue.md` (release evidence context)
+- `handoffs/releases/Sxxxx-release-notes.md` (target evidence when needed)
+- `docs/engineering/status-normalization-report.md` (normalization audit log)
+
+## Outputs (artifacts)
+- `docs/product/backlog.md` (target-scoped AC/status normalization when needed)
+- `docs/product/acceptance.md` (derived checklist reconciliation)
+- `handoffs/resume_brief.md` (next OPEN story + intended phase)
+- `docs/engineering/status-normalization-report.md` (audit rows)
+- `docs/engineering/state.md` (reconciliation checkpoint and evidence refs)
+
+## Stop conditions
+- Canonical conflict requires decision gate
+- Missing critical artifacts
+- Ambiguous next OPEN story / phase resolution
+
+## Canonical precedence (US-0045 / DEC-0025)
+- Story status authority is `docs/product/backlog.md` only (including **`BUG-####`** under **`## Bug issues (canonical)`** per **DEC-0061** / **US-0079**).
+- `docs/product/acceptance.md` and `docs/engineering/state.md` are derived views.
+- Reconciliation must not infer canonical story status from derived artifacts.
+- Bug portfolio drift vs **`## Bug acceptance (canonical)`** is machine-checkable: **`python scripts/bug_issue_validate.py --backlog docs/product/backlog.md --check-acceptance`** (**`BUG_RECONCILE_ACCEPTANCE_*`** codes).
+
+## Deterministic detection matrix
+1. Backlog story `Status: DONE` with unchecked AC checkboxes.
+2. Acceptance row state mismatched vs canonical backlog status.
+3. Resume intent (`next story`, `intended phase`) mismatched vs canonical OPEN backlog.
+4. Canonical/release evidence contradiction for target story (fail-closed path).
+
+## Reason codes (deterministic)
+- `STATUS_RECONCILE_APPLIED`
+- `STATUS_RECONCILE_NOOP`
+- `STATUS_RECONCILE_MISSING_INPUT`
+- `STATUS_RECONCILE_CANONICAL_CONFLICT`
+- `STATUS_RECONCILE_PHASE_AMBIGUOUS`
+- `STATUS_RECONCILE_EVIDENCE_MISSING`
+
+## Steps
+1. Read canonical and derived status artifacts.
+2. Build mismatch set using deterministic detection matrix.
+3. If no mismatches: write no-op report row + state checkpoint (`STATUS_RECONCILE_NOOP`) and stop.
+4. For each mismatched story (target-scoped only):
+   - If canonical status is `DONE`, normalize backlog AC checkboxes to checked state.
+   - Reconcile matching `docs/product/acceptance.md` row to checked state.
+5. Recompute next OPEN story by backlog priority/order:
+   - if exists, update `handoffs/resume_brief.md` to that story and intended phase `discovery`,
+   - if none exist, set intended phase `intake`.
+6. Write normalization evidence row(s) to `docs/engineering/status-normalization-report.md`:
+   - story id, prior values, resolved values, reason code, evidence refs, timestamp.
+7. Append reconciliation checkpoint to `docs/engineering/state.md` with:
+   - `phase_id=status-reconcile`
+   - `role=curator`
+   - `fresh_context_marker`
+   - `timestamp`
+   - `evidence_ref`
+8. On conflict paths (canonical/release contradiction, ambiguous phase, missing evidence):
+   - fail closed with deterministic reason code,
+   - write remediation guidance,
+   - avoid partial mutation.
+
+## Deterministic artifact ordering contract (US-0058 / DEC-0040)
+
+- Reconciliation writes must follow
+  `docs/engineering/artifact-ordering-policy.md`.
+- `docs/product/backlog.md` and `docs/product/acceptance.md` updates are
+  target-scoped and preserve sorted-canonical story order.
+- `docs/engineering/state.md` reconciliation checkpoints are append-bottom only.
+- `handoffs/resume_brief.md` updates are prepend-top in current-status section
+  without rewriting unrelated blocks.
+- Missing or ambiguous anchors must fail with
+  `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS` and no partial mutation.

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

@@ -0,0 +1,152 @@
+---
+description: "its-magic verify work: guided user acceptance testing."
+---
+
+# /verify-work
+
+## Subagents
+- qa
+
+## Execution model
+- Run `/verify-work` in a fresh QA subagent context.
+- After writing outputs, stop and hand off to `/release` (or back to `/execute`
+  if failures require fixes) in a new subagent/chat.
+
+## Isolation evidence write requirement (US-0048 / DEC-0029)
+
+At the end of `/verify-work`, append an isolation evidence entry to
+`docs/engineering/state.md`:
+
+- `phase_id=verify-work`
+- `role=qa`
+- `fresh_context_marker=<new marker for this subagent>`
+- `timestamp=<ISO UTC>`
+- `evidence_ref=<primary output ref>` (recommended: `sprints/Sxxxx/uat.json` and `sprints/Sxxxx/uat.md`)
+
+## Inputs
+
+- **Narrow-read (US-0053 / US-0096 Tranche A)**: Start at docs/engineering/phase-context.md
+  and the story section anchor in vision/architecture/decisions when a heading exists; forbid
+  full-file reads when a section heading exists.
+- `docs/product/acceptance.md`
+- `sprints/S0001/summary.md`
+
+## Outputs (artifacts)
+- `sprints/S0001/uat.json`
+- `sprints/S0001/uat.md`
+- `docs/engineering/state.md`
+
+## Stop conditions
+- Decision gate triggered
+
+## UAT lifecycle rules (DEC-0009)
+
+UAT artifacts transition from **placeholder** (created during `/sprint-plan`) to
+**populated** (filled during `/verify-work`) to **verified** (confirmed during
+`/release`). QA owns the placeholder → populated transition.
+
+### Minimum UAT content before sprint completion
+- `uat.json`: `steps` array is non-empty. Each step has a `description` and
+  `result` (`pass` or `fail`). `passed` + `failed` = total steps count.
+- `uat.md`: every UAT step is listed with its result. A results summary appears
+  at the bottom linking back to story acceptance criteria.
+- A sprint **cannot** be marked complete while UAT artifacts remain in
+  placeholder state.
+
+## Isolation compliance gate (US-0048 / DEC-0029)
+
+Before handing off to `/release`, verify isolation evidence is present and valid
+in `docs/engineering/state.md` for the target sprint lifecycle (at minimum:
+`execute`, `qa`, and `verify-work`).
+
+Fail-closed behavior (no continuation):
+
+- Missing evidence: `PHASE_CONTEXT_ISOLATION_MISSING`
+- Invalid schema/fields: `ISOLATION_EVIDENCE_INVALID`
+- Stale evidence (reused marker / pre-resume evidence): `ISOLATION_EVIDENCE_STALE`
+- Orchestrator/phase executed without fresh subagent: `PHASE_CONTEXT_ISOLATION_VIOLATION`
+
+Remediation: re-run the missing/invalid phase(s) in fresh subagent contexts and
+write new isolation evidence, then rerun `/verify-work` before proceeding to
+`/release`.
+
+## Strict runtime proof gate (US-0056 / DEC-0038)
+
+Before handing off to `/release`, verify strict runtime proof tuples are present
+and valid for the target lifecycle phases (`execute`, `qa`, `verify-work`).
+
+Fail-closed behavior (no continuation):
+
+- Missing runtime proof tuple: `RUNTIME_PROOF_MISSING`
+- Invalid tuple shape/hash/linkage: `RUNTIME_PROOF_INVALID`
+- Reused `runtime_proof_id`: `RUNTIME_PROOF_REUSED`
+- Expired proof TTL/stale proof: `RUNTIME_PROOF_STALE`
+- Ambiguous proof-to-checkpoint mapping: `RUNTIME_PROOF_AMBIGUOUS_LINK`
+
+Remediation: rerun affected phase(s) in fresh subagent contexts and write new
+strict-proof tuples linked to checkpoint evidence.
+
+## Generated-test readiness evidence gate (US-0066 / DEC-0048)
+
+Before handing off to `/release`, verify generated-test evidence is present and
+traceable for generated-project scope:
+
+- `sprints/Sxxxx/summary.md` must include generated baseline test scope/evidence refs.
+- `sprints/Sxxxx/qa-findings.md` must include generated-test auto-run evidence
+  (`command`, `result`, `output ref`, `paths ref`, reason code when failing).
+- If generated-test evidence is missing/ambiguous, fail closed with
+  `TEST_SCAFFOLD_GENERATION_FAILED` and require `/execute` or `/qa` rerun with
+  deterministic evidence capture.
+
+## Self-verify UAT probes (US-0092 / DEC-0078)
+
+When stack profile resolves, derive UAT steps from acceptance and execute probes via
+the shared resolver **`scripts/uat_probe_lib.py`** (active + `template/scripts/` mirror).
+Record evidence in **`sprints/Sxxxx/uat.json`** `probe_results[]` and
+**`sprints/Sxxxx/qa-findings.md`** (path refs for stdout/stderr — no inline secrets).
+**No silent PASS** — unresolvable steps must record fail-closed reason codes:
+
+`UAT_PROBE_UNRESOLVED`, `UAT_STACK_PROFILE_UNKNOWN`, `UAT_PROBE_TIMEOUT`,
+`UAT_PROBE_FAILED`, `UAT_PROBE_FORBIDDEN`, `UAT_PROBE_PASS`,
+`UAT_BROWSER_UNAVAILABLE`, `UAT_BROWSER_PROBE_FAILED`, `UAT_BROWSER_PROBE_TIMEOUT`.
+
+Probe catalog: **`build`**, **`test`**, **`api_health`**, **`process_health`**,
+**`browser_smoke`**, **`cli_smoke`**, **`manual_operator`**. CLI:
+`python scripts/uat_probe_lib.py --repo . --step "<acceptance step>" --report`.
+
+### Browser UAT self-test (US-0093)
+
+When **`UAT_BROWSER_PROBE_MODE=cursor`** (default) and step classifies as **`browser_smoke`**
+(or automatable **`manual_operator`** reclassified per **DEC-0079** §4), execute the **Cursor
+browser MCP** sequence — **lib never calls MCP directly** (**BUG-0006**):
+
+1. **Resolve target URL** — `docs/engineering/runtime-connectivity.md` first `http(s)://`; else
+   dev-server port from `package.json` + scratchpad **`DEV_SERVER_PORT`**.
+2. **`browser_navigate`** — load health/app URL; respect enterprise origin allowlist.
+3. **Step plan** — map acceptance verbs to **`browser_click`** / **`browser_type`** /
+   **`browser_scroll`** when automatable; **never** fill password/credential fields or read **`.env`**.
+4. **`browser_screenshot`** — write to **`sprints/Sxxxx/evidence/browser/<probe_id>-<seq>.png`**
+   (max **5** per probe).
+5. **Console + network evidence** — counts + summary path refs only (no inline secrets).
+6. **Verdict** — set **`passed`**, **`reason_code`**, **`browser_evidence_refs`** in
+   **`uat.json`** `probe_results[]`; **`passed=true`** in **`cursor`** mode **requires** non-empty
+   **`navigation_url`** + at least one screenshot or console/network summary path — else
+   **`UAT_BROWSER_PROBE_FAILED`**. Mirror under **`qa-findings.md`** **Runtime browser evidence**.
+7. **Fallback** — MCP unavailable → record **`UAT_BROWSER_UNAVAILABLE`**, run stdlib fallback when
+   **`UAT_BROWSER_FALLBACK_CHAIN=1`**; validate via
+   **`python scripts/uat_probe_lib.py --merge-result <fragment.json>`**.
+
+**No silent PASS** — stdlib alone does **not** PASS **`browser_smoke`** in **`cursor`** mode
+without agent **`browser_evidence_refs`**. Security: no auto-read **`.env`**, no credential
+auto-fill, no intake evidence mutation — **`UAT_PROBE_FORBIDDEN`** unchanged.
+
+## Steps
+1. Convert acceptance criteria into testable UAT steps. Derive steps directly from the story's acceptance criteria in `docs/product/acceptance.md`. Each AC should map to at least one UAT step. Run **`scripts/uat_probe_lib.py`** for each step where automation applies; record `probe_results[]` in **`uat.json`**.
+2. Populate UAT artifacts: write derived steps into `uat.json` (with description and result per step, accurate pass/fail counts) and `uat.md` (step list with results, summary section). Ensure UAT artifacts are in **populated** state per DEC-0009 — not placeholder.
+3. Record results and failures.
+4. Update state with pass/fail summary.
+5. Run the isolation compliance gate (above). If it fails, stop and hand off for remediation.
+6. Update traceability index in `docs/engineering/state.md`: for each story verified in this sprint, set Status to `PASS` or `FAIL` and fill the Evidence column with artifact references (e.g., `S0001/uat.json`, `S0001/summary.md`). Use the DEC-0010 format.
+7. Pre-handoff traceability check: confirm no OPEN or DONE story in the current sprint lacks a traceability index entry. If a gap is found, add the missing row before proceeding with the handoff.
+8. 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/template/.cursor/dev-environment.json.example

@@ -0,0 +1,22 @@
+{
+  "schema_version": 1,
+  "detected_mode": "docker-host-local",
+  "operator_seeded": true,
+  "last_updated": "2026-06-14T00:00:00Z",
+  "compose_file": "docker-compose.yml",
+  "service": "app",
+  "target_id": "",
+  "connect": {
+    "endpoint": "http://localhost:3000",
+    "health_path": "/health",
+    "hostEnv": "DEV_HOST",
+    "portEnv": "DEV_PORT",
+    "protocolEnv": "DEV_PROTOCOL"
+  },
+  "rebuild_recipe": {
+    "default_tier": "B",
+    "restart_on_source_change": false
+  },
+  "env_refs": ["DEV_HOST", "DEV_PORT", "DEV_PROTOCOL"],
+  "evidence_refs": ["sprints/S0088/summary.md"]
+}

package/{.cursor → template/.cursor}/hooks/README.md

@@ -1,4 +1,4 @@
-# GSD hooks
+# its-magic hooks
 
 This folder contains a minimal hook dispatcher for Cursor.
 
@@ -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/gsd-hook.py → template/.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")
-STATE_FILE = os.path.join(ROOT, ".cursor", "hooks", "gsd-hook-state.json")
-BENCH_LOG = os.path.join(ROOT, ".cursor", "hooks", "gsd-bench-log.jsonl")
+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:
@@ -47,7 +56,7 @@ def save_state(state):
 
 
 def bench_session(flags):
-    session = flags.get("GSD_BENCH_SESSION", "").strip()
+    session = flags.get("MAGIC_BENCH_SESSION", "").strip()
     return session if session else None
 
 
@@ -179,7 +188,7 @@ def main():
 
     if event == "stop":
         log_bench_event(session, event, payload)
-        strict = flags.get("GSD_CONTEXT_STRICT", "0") == "1"
+        strict = flags.get("MAGIC_CONTEXT_STRICT", "0") == "1"
         done = flags.get("DONE", "0") == "1"
         if strict and state.get("code_changed") and not state.get("context_refreshed"):
             if not done:

package/template/.cursor/hooks.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": "python .cursor/hooks/hook.py beforeShellExecution"
+      }
+    ],
+    "beforeReadFile": [
+      {
+        "command": "python .cursor/hooks/hook.py beforeReadFile"
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "python .cursor/hooks/hook.py afterFileEdit"
+      }
+    ],
+    "stop": [
+      {
+        "command": "python .cursor/hooks/hook.py stop"
+      }
+    ]
+  }
+}
+

package/template/.cursor/remote.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "defaultTarget": "local-docker",
+  "targets": [
+    {
+      "id": "local-docker",
+      "type": "docker",
+      "enabled": true,
+      "host": "127.0.0.1",
+      "port": 2375,
+      "workspaceRoot": "/workspace",
+      "auth": {
+        "mode": "env",
+        "tokenEnv": "REMOTE_DOCKER_TOKEN"
+      }
+    },
+    {
+      "id": "remote-vm-ssh",
+      "type": "ssh",
+      "enabled": false,
+      "host": "vm.example.internal",
+      "port": 22,
+      "workspaceRoot": "/home/dev/workspace",
+      "auth": {
+        "mode": "env",
+        "usernameEnv": "REMOTE_SSH_USER",
+        "privateKeyPathEnv": "REMOTE_SSH_KEY_PATH"
+      }
+    }
+  ]
+}