its-magic 0.1.2-9 → 0.1.3-0

package/template/.cursor/commands/pause.md

@@ -0,0 +1,64 @@
+---
+description: "its-magic pause: write checkpoint and resume brief."
+---
+
+# /pause
+
+## Subagents
+- curator
+
+## Execution model
+- Run `/pause` in a fresh Curator subagent context.
+- After writing outputs, stop.
+
+## Isolation evidence write requirement (US-0048 / DEC-0029)
+
+At the end of `/pause`, append an isolation evidence entry to
+`docs/engineering/state.md`:
+
+- `phase_id=pause`
+- `role=curator`
+- `fresh_context_marker=<new marker for this subagent>`
+- `timestamp=<ISO UTC>`
+- `evidence_ref=handoffs/resume_brief.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.
+- Current sprint progress and state
+- Optional intent: immediate pause or graceful pause after current boundary
+
+## Outputs (artifacts)
+- `docs/engineering/state.md`
+- `sprints/S0001/progress.md`
+- `handoffs/resume_brief.md`
+
+## Stop conditions
+- Missing state or progress updates
+
+## Steps
+1. Write a short checkpoint of current work.
+2. Update sprint progress and state.
+3. Record deterministic continuation breadcrumbs in `docs/engineering/state.md`:
+   - `invocation_mode=auto|manual`
+   - `requested_start_from`
+   - `resolved_start_phase`
+   - `resolution_source`
+   - `resolution_status`
+   - `stop_reason=pause_request|manual_pause`
+   - `stop_phase`
+   - `timestamp`
+4. Write `handoffs/resume_brief.md` with next actions and canonical intended
+   resume phase (`intake|discovery|research|architecture|sprint-plan|plan-verify|execute|qa|verify-work|release|refresh-context`).
+   - Include isolation provenance (US-0048 / DEC-0029):
+     - `isolation_provenance_ref` pointing to the latest isolation evidence entry
+       in `docs/engineering/state.md`
+     - `resume_requires_fresh_context=1` (resume must run the next phase in a
+       fresh subagent and write new isolation evidence; no marker reuse)
+5. If pause metadata is stale or ambiguous, fail fast with:
+   `[AUTO_RESUME_ERROR] <code>: <summary>. Source=<source>. Fix: <action>.`
+6. If this pause was requested via `AUTO_PAUSE_REQUEST=1`, reset the flag to `0`
+   after checkpoint is complete.
+

package/{.cursor/commands/gsd-phase-context.md → template/.cursor/commands/phase-context.md}

@@ -1,14 +1,18 @@
 ---
-description: "GSD phase context: capture phase preferences and constraints."
+description: "its-magic phase context: capture phase preferences and constraints."
 ---
 
-# /gsd-phase-context
+# /phase-context
 
 ## Subagents
 - po
 - tech-lead
 
 ## 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.
 - Phase name (intake, discovery, architecture, sprint-plan, execute, qa, release)
 - Preferences, constraints, UX requirements
 

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

@@ -0,0 +1,34 @@
+---
+description: "its-magic plan verify: verify sprint tasks against acceptance."
+---
+
+# /plan-verify
+
+## Subagents
+- tech-lead
+
+## Execution model
+- Run `/plan-verify` in a fresh Tech Lead subagent context.
+- After writing outputs, stop and hand off to `/execute` 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.
+- `sprints/S0001/tasks.md`
+- `docs/product/acceptance.md`
+- `docs/engineering/architecture.md`
+
+## Outputs (artifacts)
+- `sprints/S0001/plan-verify.json`
+- `docs/engineering/state.md`
+
+## Stop conditions
+- Tasks do not cover acceptance criteria
+- Decision gate triggered
+
+## Steps
+1. Check each acceptance criterion against tasks.
+2. Record gaps and required changes in `plan-verify.json`.
+3. Update state and handoff if needed.

package/template/.cursor/commands/qa.md

@@ -0,0 +1,226 @@
+---
+description: "its-magic QA: test plan, findings, verify fixes."
+---
+
+# /qa
+
+## Subagents
+- qa
+
+## Execution model
+- Run `/qa` in a fresh QA subagent context.
+- After writing outputs, stop and hand off to `/execute` (if issues) or
+  `/verify-work` (if clear) in a new subagent/chat.
+- Each QA pass in the implementation loop must be a new QA subagent.
+
+## Isolation evidence write requirement (US-0048 / DEC-0029)
+
+At the end of `/qa`, append an isolation evidence entry to
+`docs/engineering/state.md`:
+
+- `phase_id=qa`
+- `role=qa`
+- `fresh_context_marker=<new marker for this subagent>`
+- `timestamp=<ISO UTC>`
+- `evidence_ref=<primary output ref>` (recommended: `sprints/Sxxxx/qa-findings.md` and/or `handoffs/qa_to_dev.md`)
+
+In an execute↔QA implementation loop (`AUTO_IMPLEMENTATION_LOOP=1`), each new
+`/qa` cycle must have a new `fresh_context_marker` (marker reuse is treated as
+stale isolation evidence).
+
+## 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.
+- `handoffs/dev_to_qa.md`
+- `sprints/S0001/summary.md`
+
+## Outputs (artifacts)
+- `sprints/S0001/qa-findings.md`
+- `handoffs/qa_to_dev.md` (if issues)
+- `docs/engineering/state.md`
+
+## Stop conditions
+- Critical defects require decision
+- Missing test plan coverage
+
+## Release gate prerequisite (US-0039)
+
+QA completion evidence is required before `/release` may proceed. Record findings in
+`sprints/Sxxxx/qa-findings.md`; unresolved blocking findings block release with
+`RELEASE_QA_BLOCKERS_OPEN`. When clear, handoff to `/verify-work` so release gate can
+verify no unresolved blockers.
+
+## Self-verify UAT probes (US-0092 / DEC-0078)
+
+Share the **`scripts/uat_probe_lib.py`** resolver with **`/verify-work`**: derive
+acceptance steps, execute probes where stack profile resolves, record evidence in
+**`sprints/Sxxxx/uat.json`** `probe_results[]` and **`sprints/Sxxxx/qa-findings.md`**.
+Fail closed with **`UAT_PROBE_UNRESOLVED`** (not PASS) when no probe maps.
+Forbidden: auto-read **`.env`**, mutate intake evidence — **`UAT_PROBE_FORBIDDEN`**.
+
+Reason codes extend with **`UAT_BROWSER_UNAVAILABLE`**, **`UAT_BROWSER_PROBE_FAILED`**,
+**`UAT_BROWSER_PROBE_TIMEOUT`** (**US-0093** / **DEC-0079**).
+
+### 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
+0. If `SECURITY_REVIEW=1`, verify `docs/engineering/security-review.md` exists
+   and has no unresolved `critical` findings before proceeding. If unresolved
+   critical findings exist, stop at a decision gate.
+1. Define a test plan and run verification using the runbook commands
+   (`TEST_COMMAND`, `LINT_COMMAND`, `TYPECHECK_COMMAND` in `docs/engineering/runbook.md`).
+   - `TEST_COMMAND` is mandatory baseline evidence for push eligibility.
+   - Optional checks run only when configured and should be reported as
+     `pass|fail|skipped` deterministically.
+   - **User-visible metadata guard (US-0071 / DEC-0053):** run
+     `python scripts/check-user-visible-metadata.py` (see runbook). On failure,
+     record blocking findings with reason `USER_VISIBLE_INTERNAL_METADATA_DETECTED`,
+     cite `path:line:column` evidence, token class, and remediation per runbook.
+     If the checker entrypoint is missing, fail closed with
+     `METADATA_SANITIZATION_POLICY_MISSING`.
+2. Record findings and severity.
+   - Explicitly classify blockers that must prevent auto-push:
+     unresolved blocking QA findings and unresolved critical issues.
+3. Update state and handoff to dev if needed.
+   - For sync-policy evidence, include deterministic `reason_code` guidance:
+     - `PRE_QA_AUTOPUSH_FORBIDDEN` (feature work before QA completion)
+     - `BLOCKING_QA_FINDINGS` (open blockers/criticals)
+     - `SYNC_PUSHED` (eligible + checks passed + branch safe)
+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.
+8. Optional compatibility observability QA checks (US-0034):
+   - If `CROSS_REPO_OBSERVABILITY=0`, add zero required compatibility overhead.
+   - If `CROSS_REPO_OBSERVABILITY=1`, verify compatibility artifacts exist and
+     are current (`docs/engineering/compatibility-signals.md`,
+     `docs/engineering/compatibility-report.md`) with traceable references to
+     story/sprint/task context.
+   - If unresolved critical compatibility findings exist and
+     `COMPATIBILITY_GATE_ON_CRITICAL=1`, mark as release-blocking and require
+     decision gate before `/release`.
+9. Optional component-scope protection checks (US-0035):
+   - If `COMPONENT_SCOPE_MODE=0`, add zero required protection overhead.
+   - If `COMPONENT_SCOPE_MODE=1`, verify unaffected-component protection checks
+     for declared `non_target_components` and record evidence in
+     `docs/engineering/component-scope-report.md`.
+   - If unapproved out-of-scope impact is detected, mark as blocking and require
+     decision gate before `/release`.
+10. Optional spec-pack verification (US-0031):
+   - If `SPEC_PACK_MODE=0`, add no required spec-pack checks (zero overhead).
+   - If `SPEC_PACK_MODE=1`, verify target-story spec-pack artifacts exist and
+     required sections are populated; report gaps in qa-findings; see runbook
+     for minimum sections and traceability.
+11. Optional user-guide verification (US-0032):
+   - If `USER_GUIDE_MODE=0`, add no required user-guide checks or blocking (zero overhead).
+   - If `USER_GUIDE_MODE=1`, verify target-story user guide exists at
+     `docs/user-guides/US-xxxx.md` and required sections are present; report
+     gaps in qa-findings; see runbook for minimum schema.
+12. Optional remote runtime QA/debug contract (US-0064):
+   - When remote runtime metadata exists in
+     `docs/engineering/release-targets.json` for active target context,
+     validate remote endpoint reachability/debug evidence per configured
+     `runtime.mode`.
+   - Include local vs remote QA context and sanitized endpoint details in
+     `sprints/Sxxxx/qa-findings.md`.
+   - If remote connectivity config is incomplete for required remote checks,
+     mark blocking with deterministic reason code
+     `REMOTE_CONNECTIVITY_CONFIG_INVALID`.
+   - **US-0084**: when `REMOTE_EXECUTION=1`, expect **`handoffs/dev_to_qa.md`**
+     to carry an **environment label** (`WSL`, `ssh:<hostEnv>`, `dockerOverSsh`, …)
+     and **test locus** (local vs remote); reject evidence that pastes secret
+     values (keys/passwords) — **names-only** refs align with
+     `python scripts/remote_config_summary.py` output.
+13. Runtime QA autopilot contract (US-0065 / DEC-0047):
+   - Runtime truth path is mandatory for generated-project QA:
+     `startup -> readiness/connectivity -> log scan -> bounded retry -> verdict`.
+   - PASS requires runtime startup and endpoint/process reachability evidence.
+   - Deterministic failure outcomes:
+     - startup command/process fails: `RUNTIME_STARTUP_FAILED`
+     - endpoint/process unreachable after retries:
+       `RUNTIME_ENDPOINT_UNREACHABLE`
+     - critical runtime log signals detected:
+       `RUNTIME_LOG_CRITICAL_DETECTED`
+     - retry budget exhausted without recovery:
+       `RUNTIME_RETRY_BUDGET_EXHAUSTED`
+     - stack profile unresolved for runtime checks:
+       `RUNTIME_STACK_PROFILE_UNRESOLVED`
+   - Runtime profile resolution must be stack-aware for:
+     `node|python|go|java|dotnet` at minimum.
+   - Unknown/ambiguous stacks must fail closed with
+     `RUNTIME_STACK_PROFILE_UNRESOLVED` (no silent generic PASS fallback).
+   - Bounded retry loop requirements:
+     - retry only transient startup/connectivity failures,
+     - enforce configured attempt cap (`attempt <= max`),
+     - write per-attempt ledger evidence (`attempt`, `delay_ms`, `outcome`),
+     - stop retrying on non-transient critical log failures.
+   - Required QA runtime evidence schema fields in `sprints/Sxxxx/qa-findings.md`:
+     - `runtime_startup_command`
+     - `runtime_stack_profile`
+     - `runtime_mode` (`local|remote`)
+     - `runtime_health_target` (process/endpoint)
+     - `runtime_health_result`
+     - `runtime_log_summary` (severity counts + key signals)
+     - `runtime_retry_count`
+     - `runtime_retry_ledger`
+     - `runtime_final_verdict` (`pass|fail`)
+     - `runtime_reason_code`
+     - `runtime_evidence_refs`
+   - Webapp runtime verification path (when applicable):
+     - run browser-surface check for expected app load path,
+     - capture console error summary and failed network request summary,
+     - include results in runtime evidence fields.
+   - Optional debug escalation path:
+     - use only for reproducible runtime failures,
+     - keep instrumentation bounded and reversible,
+     - record debug actions/evidence and cleanup confirmation.
+14. Generated baseline test auto-run contract (US-0066 / DEC-0048):
+   - For generated-project QA scope, run baseline tests automatically using the
+     resolved `TEST_COMMAND`; do not treat baseline tests as optional.
+   - Deterministic generated-test evidence fields in `sprints/Sxxxx/qa-findings.md`:
+     - `generated_test_stack_profile`
+     - `generated_test_command`
+     - `generated_test_result` (`pass|fail`)
+     - `generated_test_output_ref`
+     - `generated_test_paths_ref`
+     - `generated_test_reason_code`
+   - Deterministic scaffold failure outcomes:
+     - unresolved profile: `TEST_SCAFFOLD_STACK_UNRESOLVED`
+     - unsupported profile: `TEST_SCAFFOLD_UNSUPPORTED_STACK`
+     - generation/run failure: `TEST_SCAFFOLD_GENERATION_FAILED`
+   - Non-destructive baseline guardrails:
+     - preserve user-authored tests/config/commands,
+     - validate generated scaffold behavior as fill-missing/idempotent only.
+   - Runtime integration boundary:
+     - generated-test PASS does not override runtime-autopilot failures from
+       `US-0065`; non-starting apps cannot PASS QA.
+

package/template/.cursor/commands/quick.md

@@ -0,0 +1,41 @@
+---
+description: "its-magic quick: execute a small task without full planning."
+---
+
+# /quick
+
+## Subagents
+- dev
+
+## Execution model
+- Run `/quick` in a fresh Dev subagent context.
+- After writing outputs, stop. Any follow-up starts in a new subagent/chat.
+
+## Inputs
+- Task description
+- **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.
+
+## `/auto` routing (US-0096 / DEC-0082)
+
+When **`DELIVERY_MODE=mega_quick`** and eligibility passes, **`/auto`** materializes this
+command only (`resolved_phase_plan = ["quick"]`). See **`.cursor/commands/auto.md`** §
+**`mega_quick` routing** for seven **`MEGA_QUICK_*`** fail-closed codes and
+**`DELIVERY_MODE_INELIGIBLE`** handling.
+
+Artifacts under **`sprints/quick/Qxxxx/`**: **`task.json`** + **`summary.md`**. Second spawn
+only on test failure. Closure requires **`acceptance_met: true`** + green tests.
+
+## Outputs (artifacts)
+- `sprints/quick/Q0001/task.json`
+- `sprints/quick/Q0001/summary.md`
+- `docs/engineering/state.md`
+
+## Stop conditions
+- Decision gate triggered
+
+## Steps
+1. Define the task in `task.json`.
+2. Implement the change quickly.
+3. Write a short summary and update state.

package/template/.cursor/commands/refresh-context.md

@@ -0,0 +1,82 @@
+---
+description: "its-magic refresh context: compact state and decisions."
+---
+
+# /refresh-context
+
+## Subagents
+- curator
+
+## Execution model
+- Run `/refresh-context` in a fresh Curator subagent context.
+- After writing outputs, stop. Next phase starts 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.
+- Current sprint artifacts
+- Decisions and handoffs
+
+## Outputs (artifacts)
+- `docs/engineering/state.md`
+- `docs/engineering/decisions.md`
+- `sprints/S0001/summary.md`
+
+## Stop conditions
+- Missing critical artifacts
+
+## Steps
+1. Compact state and decisions into a short context pack.
+2. Update sprint summary with current status.
+3. Ensure handoffs and state are consistent.
+3a. Optional codebase map refresh (US-0082 / DEC-0065): when merged scratchpad
+    sets `CODEBASE_MAP_REFRESH_ON_ROLLOVER=1`, from repository root run
+    `python scripts/materialize_codebase_map.py --trigger refresh-context`.
+    Default is **skip** (omit this step) to avoid map churn. On
+    `CODEBASE_MAP_BLOCKED:*`, record the token and remediation in the new
+    `state.md` checkpoint; do not rewrite operator-authored maps outside the
+    bootstrap contract.
+4. Enforce **triad** hot-surface rollover when merged scratchpad thresholds are
+   exceeded (DEC-0054):
+   - read caps from `.cursor/scratchpad.md` + `.cursor/scratchpad.local.md`,
+     including `STATE_HOT_MAX_LINES`, `STATE_HOT_MAX_CHECKPOINTS`,
+     `PO_TO_TL_HOT_MAX_LINES`, `PO_TO_TL_HOT_MAX_SECTIONS`, `ARCH_HOT_MAX_LINES`,
+     and `ARCH_HOT_MAX_STORY_SECTIONS` (see runbook defaults),
+   - run `python scripts/enforce-triad-hot-surface.py --rollover` from repo root
+     (or `--repo <root>`) so `state.md`, `handoffs/po_to_tl.md`, and
+     `docs/engineering/architecture.md` archive oldest contiguous units into
+     deterministic packs under `docs/engineering/state-archive/`,
+     `handoffs/archive/`, and `docs/engineering/architecture-archive/`,
+   - immediately rerun `python scripts/enforce-triad-hot-surface.py --check`;
+     on failure stop with `STATE_ARCHIVE_REQUIRED` or
+     `ARTIFACT_HOT_SURFACE_OVERSIZE` (no successful phase completion on oversize
+     hot files),
+   - record verification tuple fields (`boundary`, `moved`, `retained`,
+     `pack_ref`) in the new `state.md` checkpoint when any rollover occurred;
+     idempotent reruns must not duplicate archived content.
+
+## Deterministic artifact ordering contract (US-0058 / DEC-0040)
+
+- Writes must follow `docs/engineering/artifact-ordering-policy.md`.
+- `docs/engineering/state.md` refresh checkpoints are append-bottom only.
+- `docs/engineering/decisions.md` compact index remains newest-first in bounded
+  section while preserving canonical header structure.
+- `sprints/S0001/summary.md` context-pack pointer is prepend-top within its
+  context section; historical details remain intact.
+- Missing/ambiguous anchors fail with `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS`
+  (no partial write).
+- Archive write or rollover boundary ambiguity fails with
+  `STATE_ARCHIVE_WRITE_FAILED` or `STATE_ARCHIVE_BOUNDARY_AMBIGUOUS`
+  (no partial write).
+- Archive verification mismatch fails with `STATE_ARCHIVE_VERIFICATION_FAILED`
+  (no partial write).
+
+## Cross-phase ownership guard (US-0061 / DEC-0043)
+
+- Refresh-context mutations must comply with
+  `docs/engineering/artifact-ownership-policy.md`.
+- Only curator-owned compaction scopes may be mutated; non-owned section
+  rewrites fail closed with `PHASE_OWNERSHIP_VIOLATION`.
+