its-magic 0.1.2-9 → 0.1.2

package/template/.cursor/rules/caveman.mdc

@@ -0,0 +1,184 @@
+---
+description: "Caveman mode (US-0089) — optional response-side terse voice, default off"
+globs: ["**/*"]
+---
+
+# Caveman mode (US-0089)
+
+This rule composes an optional **response-side** terse / imperative assistant
+voice. It is **default off**. When `CAVEMAN_MODE` is unset or `0`, this rule
+adds **zero** behavioral change and the assistant responds exactly as it did
+pre-US-0089.
+
+Inspired by JuliusBrussee/caveman (MIT). External reference only; not vendored.
+
+## Scratchpad gate (authoritative across subagent spawns)
+
+Read the merged scratchpad (`.cursor/scratchpad.md`, then optional
+`.cursor/scratchpad.local.md` overrides per **DEC-0055**) for these keys:
+
+- `CAVEMAN_MODE=0|1` — default `0`. Absence is equivalent to `0`.
+- `CAVEMAN_LEVEL=lite|full|ultra` — default empty.
+  - With `CAVEMAN_MODE=0`: inert regardless of value.
+  - With `CAVEMAN_MODE=1` and `CAVEMAN_LEVEL` empty: treat as `full`
+    (mid-tier default, matching upstream reference).
+  - With `CAVEMAN_MODE=1` and a listed level: apply that level.
+  - With `CAVEMAN_MODE=1` and any other non-empty value: fail closed with
+    deterministic reason code `CAVEMAN_LEVEL_UNKNOWN` and fall back to
+    pre-US-0089 voice (no terseness applied) while continuing the turn.
+- `CAVEMAN_COMPRESS_INPUT=0|1` — **reserved for US-0090**; inert in US-0089;
+  no behavior until the compression story ships.
+- `CAVEMAN_FILE_SCOPE=` — **reserved for US-0090**; inert in US-0089; no
+  behavior until the compression story ships.
+
+Scratchpad values are **authoritative across subagent spawns**. Session
+toggle phrases (see below) are overlays for the current conversation only
+and do NOT persist across a fresh subagent context.
+
+## Literal-region invariant (9-zone hard MUST)
+
+When `CAVEMAN_MODE=1`, the following output regions remain **byte-literal**
+(no abbreviation, no rewording, no casing change). This rule is phrased as
+**MUST**, not SHOULD:
+
+1. **Fenced code blocks** — both plain triple-backtick blocks and CODE
+   REFERENCE blocks of the form `startLine:endLine:filepath`. Content, line
+   numbers, filepath, language tags, and whitespace preserved.
+2. **File / path strings** — anything matching
+   `` `[\w./-]+\.(md|py|ps1|sh|json|mdc|ts|tsx|js|jsx|yml|yaml|toml|ini|env|example|manifest)` ``
+   or enclosed in backticks that points to a repo path. Preserve extension
+   and case.
+3. **AC checklist items** — bullets of form `- [ ]` or `- [x]` and their
+   entire text (AC-1..AC-N).
+4. **Reason codes** — `ALL_CAPS_WITH_UNDERSCORES` tokens such as
+   `PHASE_CONTEXT_ISOLATION_VIOLATION`, `RUNTIME_PROOF_MISSING`,
+   `AUTO_RESUME_ERROR`, `AUTO_SCHEDULER_CONFLICT`, `REMOTE_TARGET_UNKNOWN`,
+   `CAVEMAN_LEVEL_UNKNOWN`, `INTAKE_PERSISTENCE_BLOCKED`.
+5. **IDs** — `US-xxxx`, `DEC-xxxx`, `R-xxxx`, `BUG-####`, `S0xxx`, `T-xxx`.
+6. **Contract markers** — `[BUG_VALIDATION_OK]`,
+   `[INTAKE_EVIDENCE_VALIDATION_OK]`, `[SCRATCHPAD_PAIR_OK]`,
+   `[ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS]`, `[CODEBASE_MAP_OK]`, and siblings.
+7. **Strict-proof tuple fields** — `orchestrator_run_id`, `runtime_proof_id`,
+   `proof_hash`, `proof_issued_at`, `proof_ttl_seconds`, `phase_id`, `role`
+   (DEC-0038).
+8. **Isolation evidence fields** — `fresh_context_marker`, `evidence_ref`,
+   `timestamp` (DEC-0029).
+9. **Commit / git refs** — quoted `git commit` messages, branch names, SHAs,
+   `HEAD`, tag names.
+
+Forbidden "garbling" examples (never permitted even under `ultra`): dropping
+the `US-` prefix from an ID, lowercasing a reason code, collapsing a fenced
+code block into a bullet, truncating a path mid-filename, abbreviating a
+proof hash.
+
+## Non-suppressible gate vocabulary (inherited from US-0088)
+
+Caveman voice MUST NOT remove or abbreviate the following gate tokens — they
+render byte-literal even under `CAVEMAN_LEVEL=ultra`:
+
+- `decision_gate`
+- `error`
+- `pause`
+- `loop_max`
+- `blocked`
+- `missing input`
+- `[BUG_VALIDATION_OK]`
+- `[INTAKE_EVIDENCE_VALIDATION_OK]`
+- `[SCRATCHPAD_PAIR_OK]`
+
+## Operator toggle phrases (canonical set)
+
+| Phrase | Effect |
+|--------|--------|
+| `caveman on` | Enable Caveman voice for the session (overlay). Effective from the next assistant turn. |
+| `caveman off` | Disable Caveman voice for the session (overlay). Effective from the next assistant turn. |
+| `stop caveman` | Alias for `caveman off`. |
+| `normal mode` | Alias for `caveman off`. |
+| `caveman: lite|full|ultra` | Set level for the session (implies `caveman on`). Effective from the next assistant turn. Accepts the three literal tokens `caveman: lite`, `caveman: full`, `caveman: ultra`. |
+
+Determinism rules:
+
+- Scratchpad `CAVEMAN_MODE` / `CAVEMAN_LEVEL` are **authoritative across
+  subagent spawns**; session toggles are overlays for the current
+  conversation only and do NOT persist across a fresh subagent context.
+- Within a session, the **last explicit toggle wins**.
+- A mid-turn toggle applies **from the next turn onward**; current-turn
+  machine-verifiable artifacts (gate messages, reason codes, strict-proof
+  tuples, isolation-evidence fields) remain literal regardless of the
+  toggle.
+- Ambiguous phrases (`be caveman-lite`, `quiet caveman`, `cave man off`,
+  etc.) are **not recognized** — only the exact literal matches above fire.
+
+## Composition (non-substitution) with TOKEN_PROFILE
+
+`TOKEN_PROFILE` controls context breadth. `CAVEMAN_MODE` controls reply
+voice. Neither substitutes for the other; setting one does not change the
+other. Combine freely.
+
+## Default-off invariant
+
+With `CAVEMAN_MODE=0` or absent, this rule adds zero behavioral change:
+existing command strings, gate ordering, spawn-only phrasing (BUG-0006),
+contract-test token lists, `AUTO_QUIET` non-suppressible vocabulary
+(US-0088), user-visible ID metadata (US-0071), strict-proof tuples
+(DEC-0038), and isolation evidence fields (DEC-0029) all remain unchanged.
+
+## Non-goals (US-0089)
+
+- No input-side file compression. `CAVEMAN_COMPRESS_INPUT` and
+  `CAVEMAN_FILE_SCOPE` are documented no-ops here; US-0090 owns that
+  vertical.
+- No change to `TOKEN_PROFILE` (DEC-0035 / US-0080), context packs, archive
+  policy, or phase-context slimming.
+- No rewrite of canonical artifacts (`docs/product/backlog.md`,
+  `docs/product/acceptance.md`, `docs/engineering/state.md` schema,
+  `docs/engineering/decisions.md`, DEC files).
+- No new npm / Python dependencies. No `package.json` edit.
+- No vendor plugin install. No package-manager install recipe is surfaced;
+  the JuliusBrussee/caveman reference is documentation-only.
+- No change to spawn-only orchestration (US-0048 / DEC-0029 / BUG-0006),
+  strict runtime proof (DEC-0038), `AUTO_QUIET` non-suppressible list
+  (US-0088), or US-0071 visible-metadata rules.
+
+## Voice compression (when CAVEMAN_MODE=1)
+
+### Precedence
+
+When `CAVEMAN_MODE=1`, voice-compression directives in **this rule** override
+conflicting **user rule** prose-style guidance (e.g. "write complete sentences",
+"blog-post quality") for **assistant reply voice only**; does **not** override
+user rules for tool usage, git safety, security, or commit policy.
+
+### Intensity levels
+
+| Level | Semantics | Example pattern |
+|-------|-----------|-----------------|
+| `lite` | Drop filler but keep grammatical sentences | Before: "I will now explain the orchestration gate because plan-verify requires it." After: "Orchestration gate required for plan-verify. Run gate check next." |
+| `full` | Drop articles + fragments OK | Before: "The spawn-only orchestrator must dispatch a fresh subagent for each phase." After: "Spawn-only orchestrator dispatches fresh subagent per phase. Next: run `/execute`." Pattern: `[thing] [action] [reason]. [next step].` |
+| `ultra` | Abbreviate ordinary prose words only; literals per §6 stub | Before: "The auth middleware returns HTTP 401 when the bearer token is absent from the Authorization header." After: "Auth middleware → 401. Bearer token absent. Check header." |
+
+Goal: **token-saving terse/imperative prose** — **not** stereotypical caveman
+roleplay.
+
+### Drop rules
+
+Drop articles, filler, hedging, and pleasantries where level permits; keep
+technical terms exact; fragments OK at `full` and `ultra`.
+
+### Auto-Clarity
+
+Pause compression for **security** warnings, **destructive** operations, or
+**ambiguous** compression — deliver the clear part in full prose, then resume
+Caveman voice.
+
+### Persistence
+
+Voice compression is active in **every response** while `CAVEMAN_MODE=1`;
+turn off only via scratchpad keys or the documented toggle phrases above.
+
+### Ultra and literal regions
+
+**Pointer stub** — defer to existing `## Literal-region invariant (9-zone hard
+MUST)` above. Reason codes, IDs, paths, and proof tuples remain **byte-literal**.
+At `ultra`, abbreviate ordinary prose words only — **never** abbreviate reason
+codes or gate tokens. **No duplicate** 9-zone list here.

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

@@ -0,0 +1,39 @@
+---
+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.
+- Remote config security (DEC-0016): never commit secret literals (tokens,
+  passwords, private keys) in `.cursor/remote.json`; use environment-variable
+  references only (for example `tokenEnv`, `passwordEnv`, `privateKeyPathEnv`).
+- `.env` exclusion (DEC-0071 / US-0085): do not open, attach, read, search
+  inside, or index `.env` or `.env.*` files. Use environment variable names
+  in prose only. Operators source `.env` outside agent context.
+- Automation remote routing (US-0086): when `AUTO_REMOTE_AUTOMATION_PROFILE=off`,
+  keep local behavior and never silently reroute `TEST_COMMAND` to remote.
+  Explicit NL routing is limited to `start container <target_id>` and unknown or
+  disabled targets must fail closed with documented reason codes.
+- 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/template/.cursor/rules/core.mdc

@@ -0,0 +1,111 @@
+---
+description: "Core workflow and context pack rules"
+globs: ["**/*"]
+---
+
+- Intake backlog/acceptance writes require **US-0078** evidence validation
+  (`scripts/intake_evidence_validate.py` / **DEC-0060**) before persistence; see
+  `.cursor/commands/intake.md`.
+- For first/new/broad intake, persistence also requires **US-0081** complete-plan
+  coverage contract validation (**DEC-0064**):
+  `plan_area_inventory` + `plan_area_coverage` + `coverage_complete=true`; fail
+  closed under `INTAKE_PERSISTENCE_BLOCKED` with deterministic plan-coverage
+  subcodes.
+- Defect intake uses **`INTAKE_WORK_ITEM_KIND=bug`** and/or **`/intake bug`**; validate bugs with
+  `scripts/bug_issue_validate.py` and run `scripts/intake_bug_routing_guard.py` before allocating
+  **`US-xxxx`** for defect-shaped prose (**US-0079** / **DEC-0061**).
+- Use the phase flow: intake -> discovery -> research -> architecture ->
+  [security-review: design, if SECURITY_REVIEW=1] -> sprint plan -> plan verify
+  -> execute -> [security-review: code, if SECURITY_REVIEW=1] -> QA ->
+  verify work -> release -> refresh context.
+- Enforce agent isolation: each phase must run in a fresh subagent context.
+  Never execute two delivery phases in the same agent conversation.
+- `AUTO_FLOW_MODE` controls whether phases run automatically or stop at
+  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`).
+- `SECURITY_REVIEW=1` enables optional security review insertion points:
+  post-architecture (design mode) and post-execute (code mode). When
+  `SECURITY_REVIEW=0` (default), these optional steps are skipped entirely and
+  base workflow behavior is unchanged.
+- Persist decisions and state in files; do not keep critical info only in chat.
+- Handoffs are the only cross-phase memory. When a phase writes its outputs and
+  handoff, stop that agent and start the next phase in a new subagent.
+- Pause/resume is first-class. Update `handoffs/resume_brief.md` on pause.
+- `/auto` continuation contract (DEC-0017):
+  - Support explicit `start-from=<phase>` using canonical phase IDs only:
+    `intake`, `discovery`, `research`, `architecture`, `sprint-plan`,
+    `plan-verify`, `execute`, `qa`, `verify-work`, `release`,
+    `refresh-context`.
+  - Deterministic precedence must be:
+    1) explicit `start-from`
+    2) `handoffs/resume_brief.md`
+    3) conservative `docs/engineering/state.md` fallback
+    4) fail-fast on unresolved/conflicting/ambiguous signals.
+  - Conflict/staleness policy:
+    - explicit valid override wins;
+    - if no override and `resume_brief` conflicts with inferred state, fail fast;
+    - if `resume_brief` exists but is stale or unparseable, fail fast;
+    - use state fallback only when resume brief is absent.
+  - Fail-fast contract format:
+    `[AUTO_RESUME_ERROR] <code>: <summary>. Source=<source>. Fix: <action>.`
+    Required codes:
+    `INVALID_START_FROM`, `RESUME_BRIEF_MISSING`, `RESUME_BRIEF_STALE`,
+    `RESUME_BRIEF_UNPARSEABLE`, `RESUME_STATE_CONFLICT`,
+    `STATE_PHASE_AMBIGUOUS`, `STATE_PHASE_UNRECOVERABLE`.
+  - Preserve existing stop/gate controls in continuation mode:
+    decision gate, missing critical input, pause request, loop max cycles.
+  - Write deterministic breadcrumbs (`resolution_source`, chosen phase,
+    `stop_reason`, `stop_phase`, `timestamp`) to `docs/engineering/state.md`
+    and `handoffs/resume_brief.md` (when stopped before completion).
+- Context pack must stay compact: summarize, do not dump raw logs.
+- Remote execution contract (DEC-0016):
+  - If `REMOTE_EXECUTION=0` (default), skip remote config validation and keep
+    workflow overhead at zero.
+  - If `REMOTE_EXECUTION=1`, validate `.cursor/remote.json` before any remote
+    build/test activity and fail fast on blocking issues.
+  - Required root fields: `version`, `defaultTarget`, `targets`.
+  - Required target fields: `id`, `type`, `enabled`, `host`, `port`,
+    `workspaceRoot`.
+  - Allowed `type` values: `docker`, `ssh`, `vm`.
+  - `defaultTarget` must reference an existing enabled target id.
+  - No committed secrets in config; sensitive values must be env-var references.
+  - If valid, agents may use configured remote/docker servers for builds/tests.
+- Release queue and per-sprint notes contract (DEC-0020):
+  - `/verify-work` declares sprint readiness in state context (`ready` intent).
+  - `/release` owns target-sprint-only queue transitions and sprint-scoped note
+    writing:
+    `planned|ready -> unreleased -> released`.
+  - Canonical artifacts are `handoffs/release_queue.md` and
+    `handoffs/releases/Sxxxx-release-notes.md`.
+  - `handoffs/release_notes.md` remains legacy-compatible pointer/summary only.
+  - On unresolved sprint identity or queue/notes mismatch, fail closed with
+    deterministic reason codes and remediation guidance; no destructive
+    reconciliation.
+- Release gate no-bypass (US-0039 / DEC-0019):
+  - Default behavior is strict no-bypass for release gates.
+  - Overrides require explicit decision evidence with rationale and risk
+    acceptance.
+- Release operator hints contract (US-0067 / DEC-0049):
+  - `/release` output must include deterministic sections:
+    `Run -> Connect -> Verify -> Credentials -> Known Issues`.
+  - Required fields include start command, runtime mode/context ref, endpoint +
+    port + health endpoint, verification steps, credentials source refs
+    (env-ref-only), and known issues.
+  - Missing/ambiguous fields or inline secrets fail closed with
+    `RELEASE_OPERATOR_HINTS_MISSING`,
+    `RELEASE_OPERATOR_HINTS_AMBIGUOUS`, or
+    `RELEASE_OPERATOR_HINTS_SECRET_EXPOSURE`.
+- Cross-phase artifact ownership guard (US-0061 / DEC-0043):
+  - All delivery phases must enforce
+    `docs/engineering/artifact-ownership-policy.md` before mutating artifacts.
+  - Non-authorized phases must not delete or rewrite other-phase owned sections.
+  - On prohibited mutation, fail closed with `PHASE_OWNERSHIP_VIOLATION`.
+  - If an override-authorized mutation path is allowed but evidence is missing,
+    fail closed with `PHASE_OVERRIDE_EVIDENCE_MISSING`.
+

package/template/.cursor/rules/handoffs.mdc

@@ -0,0 +1,27 @@
+---
+description: "Handoffs and artifact persistence"
+globs: ["**/*"]
+---
+
+- Every role writes handoffs to files; nothing important stays in chat only.
+- Every handoff boundary requires a fresh agent context for the receiving role.
+- Do not continue across roles in one conversation; write the handoff, stop,
+  then start the next role in a new subagent/chat.
+- Update sprint `summary.md` and `progress.md` after task completion.
+- Use `handoffs/*.md` for role-to-role transfers.
+- Keep `docs/engineering/state.md` current and concise.
+- Release handoff touchpoints (US-0040):
+  - `/verify-work` handoff should identify release-ready target sprint context.
+  - `/release` handoff should reference canonical sprint notes path:
+    `handoffs/releases/Sxxxx-release-notes.md`.
+  - `/release` handoff should reference queue state in
+    `handoffs/release_queue.md`, including any fail-safe reason codes.
+  - If `/release` is blocked post-QA, write/update
+    `sprints/Sxxxx/release-findings.md` and hand off remediation via
+    `handoffs/release_to_dev.md`.
+  - `handoffs/release_notes.md` is maintained as backward-compatible
+    latest-pointer summary.
+- User-guide traceability (US-0032): When `USER_GUIDE_MODE=1`, handoffs and
+  release context should reference the canonical user guide for the target
+  story: `docs/user-guides/US-xxxx.md` (story ID maps 1:1 to guide artifact).
+

package/template/.cursor/rules/quality.mdc

@@ -0,0 +1,49 @@
+---
+description: "Quality gates and small-step execution"
+globs: ["**/*"]
+---
+
+- Prefer small, atomic changes tied to a single task.
+- 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
+  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.
+- Scripts that call subprocesses must use timeouts to prevent infinite hangs.
+  Use `-NonInteractive` for PowerShell, `< /dev/null` for sh, and respect
+  `TEST_TIMEOUT_SECONDS` from the runbook. Never use `Read-Host` or `read`
+  in code paths reachable without user interaction.
+- 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 `bash 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.
+- Remote config validation errors (when `REMOTE_EXECUTION=1`) must be fail-fast
+  and actionable using this format:
+  `[REMOTE_CONFIG_ERROR] <path>: expected <rule>, got <actual>. Fix: <hint>.`
+  Include all of: failing path, expected rule/range, actual value or type, and
+  a concrete remediation hint.
+- Runtime QA autopilot failures (US-0065) must use deterministic reason codes
+  and evidence:
+  `RUNTIME_STARTUP_FAILED`, `RUNTIME_ENDPOINT_UNREACHABLE`,
+  `RUNTIME_LOG_CRITICAL_DETECTED`, `RUNTIME_RETRY_BUDGET_EXHAUSTED`,
+  `RUNTIME_STACK_PROFILE_UNRESOLVED`.
+  Include startup command/profile, runtime mode, health result, retry ledger,
+  and log summary in QA artifacts.
+- User-visible internal metadata (US-0071 / DEC-0053): do not introduce
+  planning-shaped tokens (`US-[0-9]{4}`, `DEC-[0-9]{4}`, `R-[0-9]{4}`) into
+  operator-visible strings under inclusive scan roots (`bin/`, root installers,
+  `packaging/**`, `scripts/validate-and-push.*`). Use
+  `python scripts/check-user-visible-metadata.py` before handoff; on leakage use
+  `USER_VISIBLE_INTERNAL_METADATA_DETECTED` with path evidence and remediation
+  per `docs/engineering/runbook.md`.
+