its-magic 0.1.2-27 → 0.1.2-29

package/README.md

@@ -225,6 +225,37 @@ Intake runtime safety behavior (US-0059):
   writers; true conflicting external writes fail safe with
   `INTAKE_CONCURRENT_WRITER_DETECTED`.
 
+Runtime QA autopilot behavior (US-0065):
+- Generated-project QA must include runtime proof chain:
+  `startup -> readiness/connectivity -> log scan -> bounded retry -> verdict`.
+- Deterministic runtime fail codes:
+  `RUNTIME_STARTUP_FAILED`, `RUNTIME_ENDPOINT_UNREACHABLE`,
+  `RUNTIME_LOG_CRITICAL_DETECTED`, `RUNTIME_RETRY_BUDGET_EXHAUSTED`,
+  `RUNTIME_STACK_PROFILE_UNRESOLVED`.
+- Runtime evidence must include startup command/profile, runtime mode
+  (`local|remote`), health result, retry ledger, and log severity summary.
+- Stack-aware runtime profile resolution is required for Node/Python/Go/Java/.NET;
+  unresolved stacks fail closed (no generic silent PASS fallback).
+- For webapp contexts, QA includes browser-surface verification with
+  console/network error signals.
+
+Generated test scaffolding + auto-run behavior (US-0066):
+- `/execute` resolves stack profile (`node|python|go|java|dotnet`) and generates
+  missing baseline unit/integration/acceptance tests only.
+- Generation is non-destructive by default: preserve user-authored tests/config,
+  fill only missing baseline assets, keep reruns idempotent.
+- `TEST_COMMAND` wiring is deterministic:
+  - preserve existing non-empty user command,
+  - set stack baseline only when command is missing/unset.
+- `/qa` automatically runs the generated baseline tests and records deterministic
+  evidence (`command`, `result`, `output ref`, `generated paths ref`).
+- Fail-closed scaffold diagnostics:
+  `TEST_SCAFFOLD_STACK_UNRESOLVED`,
+  `TEST_SCAFFOLD_UNSUPPORTED_STACK`,
+  `TEST_SCAFFOLD_GENERATION_FAILED`.
+- Static baseline test pass does not bypass runtime autopilot; runtime verdict
+  remains mandatory for QA PASS.
+
 ## Workflow
 
 ### Core commands
@@ -277,6 +308,34 @@ broad/high-risk requests:
   (`docs/product/backlog.md`, `docs/product/acceptance.md`,
   `handoffs/po_to_tl.md`)
 
+### Mandatory intake question packs (US-0068)
+
+`/intake` now enforces deterministic minimum questionnaire packs before
+backlog/acceptance persistence:
+
+- `first-intake-pack` for first/new/broad requests
+- `small-intake-pack` for narrow follow-up requests
+
+Fail-closed coverage behavior:
+
+- required topic answers must be covered for the selected pack before write
+- unknown/ambiguous stack cues fail closed to `first-intake-pack`
+- persistence blocks with deterministic reason codes when required coverage is
+  incomplete and assumptions are not explicitly confirmed
+
+Deterministic reason codes:
+
+- `INTAKE_REQUIRED_TOPIC_MISSING`
+- `INTAKE_REQUIRED_PACK_INCOMPLETE`
+- `INTAKE_ASSUMPTION_CONFIRMATION_REQUIRED`
+- `INTAKE_PERSISTENCE_BLOCKED`
+
+Intake artifacts must persist coverage evidence fields:
+
+- `asked_topics`
+- `missing_topics`
+- `assumptions_confirmed`
+
 ### Optional ID namespace bootstrap (US-0052)
 
 Fresh-project ID bootstrap behavior is explicit and default-off:

package/installer.ps1

@@ -111,7 +111,7 @@ function Choose-Mode {
 function Classify-File($RelPath) {
   $normalized = $RelPath -replace '\\','/'
 
-  $mixedFiles = @('.cursor/scratchpad.md')
+  $mixedFiles = @('.cursor/scratchpad.md', 'README.md')
   if ($mixedFiles -contains $normalized) { return 'mixed' }
 
   $frameworkPrefixes = @(
@@ -174,6 +174,15 @@ function Write-InstalledVersion($TargetRoot, $Ver) {
   }
 }
 
+function Sync-RootReadmeToItsMagic($TargetRoot) {
+  $rootReadme = Join-Path $TargetRoot "README.md"
+  if (-not (Test-Path $rootReadme -PathType Leaf)) { return $false }
+  $itsMagicReadme = Join-Path $TargetRoot "its_magic\README.md"
+  Ensure-Parent $itsMagicReadme
+  Copy-Item -Path $rootReadme -Destination $itsMagicReadme -Force
+  return $true
+}
+
 function Read-RunbookKeyValue($RunbookPath, $Key) {
   if (-not (Test-Path $RunbookPath -PathType Leaf)) { return "" }
   $needle = "${Key}:"
@@ -617,6 +626,7 @@ if ($mode -eq "upgrade") {
   }
 
   Write-InstalledVersion $targetRoot $appVersion
+  Sync-RootReadmeToItsMagic $targetRoot | Out-Null
   $runbookBootstrap = Invoke-RunbookBootstrap -TargetRoot $targetRoot
   foreach ($note in $runbookBootstrap.notes) { Write-Host $note }
   if (-not $runbookBootstrap.ok) { exit 1 }
@@ -694,6 +704,7 @@ foreach ($rel in $files) {
 }
 
 Write-InstalledVersion $targetRoot $appVersion
+Sync-RootReadmeToItsMagic $targetRoot | Out-Null
 $runbookBootstrap = Invoke-RunbookBootstrap -TargetRoot $targetRoot
 foreach ($note in $runbookBootstrap.notes) { Write-Host $note }
 if (-not $runbookBootstrap.ok) { exit 1 }

package/installer.py

@@ -119,7 +119,7 @@ USER_DATA_PREFIXES = (
     "docs/product/", "docs/engineering/", "docs/user-guides/",
     "sprints/", "handoffs/", "decisions/",
 )
-MIXED_FILES = {".cursor/scratchpad.md"}
+MIXED_FILES = {".cursor/scratchpad.md", "README.md"}
 
 
 def classify_file(rel_path):
@@ -159,6 +159,16 @@ def write_installed_version(target_root, ver):
         os.remove(legacy)
 
 
+def sync_root_readme_to_its_magic(target_root):
+    root_readme = os.path.join(target_root, "README.md")
+    if not os.path.isfile(root_readme):
+        return False
+    its_magic_readme = os.path.join(target_root, "its_magic", "README.md")
+    ensure_parent(its_magic_readme)
+    shutil.copy2(root_readme, its_magic_readme)
+    return True
+
+
 def read_runbook_key(runbook_path, key):
     if not os.path.isfile(runbook_path):
         return ""
@@ -550,6 +560,7 @@ def main():
                 continue
 
         write_installed_version(target_root, version)
+        sync_root_readme_to_its_magic(target_root)
         runbook_ok, runbook_notes = bootstrap_runbook_commands(target_root)
         for note in runbook_notes:
             print(note)
@@ -620,6 +631,7 @@ def main():
                 shutil.copy2(src, dst)
 
     write_installed_version(target_root, version)
+    sync_root_readme_to_its_magic(target_root)
     runbook_ok, runbook_notes = bootstrap_runbook_commands(target_root)
     for note in runbook_notes:
         print(note)

package/installer.sh

@@ -133,7 +133,7 @@ choose_mode() {
 classify_file() {
   rel="$1"
   case "$rel" in
-    .cursor/scratchpad.md) echo "mixed" ;;
+    .cursor/scratchpad.md|README.md) echo "mixed" ;;
     .cursor/commands/*|.cursor/rules/*|.cursor/agents/*|.cursor/skills/*) echo "framework" ;;
     .cursor/hooks/*|.cursor/hooks.json|.cursor/scratchpad.local.example.md) echo "framework" ;;
     .github/workflows/*|scripts/validate-and-push*|docs/engineering/context/*|its_magic/*) echo "framework" ;;
@@ -166,6 +166,15 @@ write_installed_version() {
   [ -f "$legacy" ] && rm -f "$legacy"
 }
 
+sync_root_readme_to_its_magic() {
+  target_root="$1"
+  [ -f "$target_root/README.md" ] || return 1
+  dst="$target_root/its_magic/README.md"
+  ensure_parent "$dst"
+  cp -p "$target_root/README.md" "$dst"
+  return 0
+}
+
 read_runbook_key() {
   runbook_path="$1"
   key="$2"
@@ -505,6 +514,7 @@ if [ "$MODE" = "upgrade" ]; then
   done
 
   write_installed_version "$TARGET_ROOT" "$APP_VERSION"
+  sync_root_readme_to_its_magic "$TARGET_ROOT" || true
   bootstrap_runbook_commands "$TARGET_ROOT"
   [ -n "$BOOTSTRAP_NOTES" ] && printf "%s" "$BOOTSTRAP_NOTES"
   [ "$BOOTSTRAP_OK" = "true" ] || exit 1
@@ -572,6 +582,7 @@ for rel in $FILES; do
 done
 
 write_installed_version "$TARGET_ROOT" "$APP_VERSION"
+sync_root_readme_to_its_magic "$TARGET_ROOT" || true
 bootstrap_runbook_commands "$TARGET_ROOT"
 [ -n "$BOOTSTRAP_NOTES" ] && printf "%s" "$BOOTSTRAP_NOTES"
 [ "$BOOTSTRAP_OK" = "true" ] || exit 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "its-magic",
-  "version": "0.1.2-27",
+  "version": "0.1.2-29",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {

package/template/.cursor/agents/po.mdc

@@ -76,3 +76,35 @@ Low-touch mode (`INTAKE_GUIDED_MODE=0`):
 - Keep duplicate/overlap backlog check active as baseline safety.
 - Keep single-story default unless user explicitly requests decomposition.
 
+Mandatory intake question packs (`US-0068` / `DEC-0050`):
+- Before persisting backlog/acceptance artifacts, select exactly one deterministic
+  question pack:
+  - `first-intake-pack` (first/new/broad intake)
+  - `small-intake-pack` (small follow-up intake)
+- Required-topic coverage is mandatory before persistence unless assumptions are
+  explicitly confirmed by the user:
+  - `first-intake-pack` required topic IDs:
+    `users_problem`, `runtime_target_environment`, `language_framework_runtime`,
+    `architecture_preference`, `ui_design_expectations`,
+    `security_compliance`, `non_functional_priorities`, `scope_timeline`
+  - `small-intake-pack` required topic IDs:
+    `outcome_success_criteria`, `impacted_components`,
+    `constraints_compatibility_risks`, `required_tests_acceptance_checks`,
+    `done_definition`
+- Deterministic pack selection guard:
+  - unknown/ambiguous stack or project cues must fail closed to
+    `first-intake-pack`.
+- Deterministic fail-closed reason codes:
+  - `INTAKE_REQUIRED_TOPIC_MISSING`
+  - `INTAKE_REQUIRED_PACK_INCOMPLETE`
+  - `INTAKE_ASSUMPTION_CONFIRMATION_REQUIRED`
+  - `INTAKE_PERSISTENCE_BLOCKED`
+- Remediation output on block must include:
+  - `missing_topics`
+  - targeted follow-up questions for unresolved required topics
+  - explicit request for assumption confirmation when assumptions are used
+- Persist auditable intake evidence in artifact outputs:
+  - `asked_topics`
+  - `missing_topics`
+  - `assumptions_confirmed`
+

package/template/.cursor/commands/execute.md

@@ -131,4 +131,55 @@ Release gate semantics (US-0039): mandatory gates (check-in test, QA, UAT) and n
      fail fast with `REMOTE_CONNECTIVITY_CONFIG_INVALID`.
    - Never expose secrets in execution outputs; only sanitized endpoint data and
      env-reference names are allowed.
+18. Runtime QA autopilot execution contract (US-0065 / DEC-0047):
+   - Treat runtime verification as mandatory for generated-project scope; static
+     checks alone are not sufficient evidence for PASS readiness.
+   - Follow canonical stage order:
+     `startup -> readiness/connectivity -> log scan -> bounded retry -> verdict`.
+   - Record runtime execution evidence in execute outputs:
+     - startup command and selected stack profile,
+     - runtime mode (`local|remote`) and endpoint/health snapshot,
+     - retry ledger (`attempt`, `delay_ms`, `outcome`),
+     - log severity summary (`info|warn|error|fatal` counts),
+     - final runtime verdict with deterministic reason code.
+   - Supported stack profiles (minimum): `node`, `python`, `go`, `java`, `dotnet`.
+   - If stack profile cannot be resolved deterministically, fail closed with
+     `RUNTIME_STACK_PROFILE_UNRESOLVED` and remediation guidance.
+   - Bounded retry policy:
+     - retries are allowed only for transient startup/connectivity failures,
+     - retry attempts must not exceed configured max,
+     - critical log signals are non-transient and fail closed immediately.
+   - Runtime failure reason-code baseline:
+     - `RUNTIME_STARTUP_FAILED`
+     - `RUNTIME_ENDPOINT_UNREACHABLE`
+     - `RUNTIME_LOG_CRITICAL_DETECTED`
+     - `RUNTIME_RETRY_BUDGET_EXHAUSTED`
+     - `RUNTIME_STACK_PROFILE_UNRESOLVED`
+   - When HTTP/UI context is detected, include webapp runtime evidence path for
+     QA handoff (browser-surface checks plus console/network error signals).
+19. Generated baseline test scaffolding contract (US-0066 / DEC-0048):
+   - Resolve deterministic stack/project profile before scaffold generation:
+     `node|python|go|java|dotnet` (minimum supported set).
+   - Generate baseline tests only when missing; create minimal runnable assets for
+     unit, integration, and acceptance layers using stable paths.
+   - Record generated-test evidence in execute outputs:
+     - resolved stack profile,
+     - generated paths inventory (`unit|integration|acceptance`),
+     - scaffold command/actions and outcome.
+   - Deterministic runbook baseline wiring:
+     - if `TEST_COMMAND` is missing/unset, write stack baseline command,
+     - if `TEST_COMMAND` is user-authored and non-empty, preserve it.
+   - Fail-closed diagnostics for generation/profile failures:
+     - `TEST_SCAFFOLD_STACK_UNRESOLVED`
+     - `TEST_SCAFFOLD_UNSUPPORTED_STACK`
+     - `TEST_SCAFFOLD_GENERATION_FAILED`
+   - Non-destructive precedence is mandatory:
+     - preserve existing user-authored test files and config by default,
+     - fill only missing baseline scaffold assets.
+   - Rerun behavior must be idempotent:
+     - no duplicate scaffold files on repeated `/execute`,
+     - no oscillating `TEST_COMMAND` rewrites between runs.
+   - Runtime boundary:
+     - static generated-test PASS is necessary but not sufficient for QA PASS;
+       runtime startup/connectivity/log verdict remains governed by `US-0065`.
 

package/template/.cursor/commands/intake.md

@@ -48,6 +48,41 @@ description: "its-magic intake: clarify idea and capture story + acceptance."
   - external conflicting mutation during active run must fail safe with
     `INTAKE_CONCURRENT_WRITER_DETECTED` and no partial overwrite.
 
+## Mandatory intake question packs and fail-closed persistence gate (US-0068 / DEC-0050)
+
+- Intake must apply one deterministic questionnaire pack before any backlog or
+  acceptance persistence:
+  - `first-intake-pack` for first/new/broad requests,
+  - `small-intake-pack` for narrow follow-up requests.
+- Pack selection must be deterministic and auditable:
+  - evaluate request breadth (`new capability` vs `bounded refinement`),
+  - use known stack/runtime cues when present,
+  - unresolved/unknown stack cues must fail closed to `first-intake-pack`
+    (never bypass to a smaller pack by default).
+- Required topic coverage must be complete before persistence unless bounded
+  assumptions are explicitly confirmed:
+  - `first-intake-pack` required topics:
+    `users_problem`, `runtime_target_environment`, `language_framework_runtime`,
+    `architecture_preference`, `ui_design_expectations`,
+    `security_compliance`, `non_functional_priorities`, `scope_timeline`.
+  - `small-intake-pack` required topics:
+    `outcome_success_criteria`, `impacted_components`,
+    `constraints_compatibility_risks`, `required_tests_acceptance_checks`,
+    `done_definition`.
+- Fail-closed deterministic reason codes:
+  - `INTAKE_REQUIRED_TOPIC_MISSING`
+  - `INTAKE_REQUIRED_PACK_INCOMPLETE`
+  - `INTAKE_ASSUMPTION_CONFIRMATION_REQUIRED`
+  - `INTAKE_PERSISTENCE_BLOCKED`
+- Remediation guidance surface (mandatory on block):
+  - list `missing_topics`,
+  - request targeted answers for missing required topics,
+  - if assumptions are used, require explicit confirmation before write.
+- Persistence evidence contract (must be written in intake outputs):
+  - `asked_topics`
+  - `missing_topics`
+  - `assumptions_confirmed`
+
 ## Steps
 1. Determine intake mode from `.cursor/scratchpad.md`:
    - guided mode: `INTAKE_GUIDED_MODE=1` (default)
@@ -94,7 +129,18 @@ description: "its-magic intake: clarify idea and capture story + acceptance."
      explicitly requests depth.
    - Keep single-story default (no forced decomposition), unless the user
      explicitly requests decomposition.
-5. Optional fresh-project ID namespace bootstrap (US-0052 / DEC-0034):
+5. Enforce mandatory question-pack coverage before persistence (US-0068):
+   - deterministically select one pack (`first-intake-pack` or
+     `small-intake-pack`) and record `selected_pack`.
+   - ask required questions for the selected pack; adaptive follow-ups remain
+     allowed but bounded.
+   - before writing backlog/acceptance artifacts, compute required coverage:
+     - if complete, proceed to persistence;
+     - if incomplete and no explicit assumption confirmation, fail closed with
+       deterministic reason code and remediation guidance.
+   - persist intake evidence fields (`asked_topics`, `missing_topics`,
+     `assumptions_confirmed`) in relevant intake artifacts.
+6. Optional fresh-project ID namespace bootstrap (US-0052 / DEC-0034):
    - Read `ID_NAMESPACE_BOOTSTRAP` from `.cursor/scratchpad.md` (`0|1`,
      default `0`).
    - Freshness eligibility is deterministic and auditable:
@@ -109,31 +155,31 @@ description: "its-magic intake: clarify idea and capture story + acceptance."
    - Never rewrite or renumber historical IDs.
    - If bootstrap was requested but checks fail, emit deterministic diagnostic:
      `ID_BOOTSTRAP_NOT_FRESH` with brief remediation guidance.
-6. Traceability persistence contract (US-0051):
+7. Traceability persistence contract (US-0051):
    - `docs/product/backlog.md`: include decomposition evidence (single-story vs
      split decision, rationale, and boundaries).
    - `docs/product/acceptance.md`: maintain acceptance traceability for resulting
      story set (or single-story decision) with clear scope boundaries.
    - `handoffs/po_to_tl.md`: include split decision summary and adaptive
      questioning evidence (risk/unknown triggers and key assumptions).
-7. Persist the story and acceptance in product docs.
-8. Write a PO -> TL handoff with scope and risks.
-9. Optional cross-repo observability declaration (US-0034):
+8. Persist the story and acceptance in product docs.
+9. Write a PO -> TL handoff with scope and risks.
+10. Optional cross-repo observability declaration (US-0034):
    - If `CROSS_REPO_OBSERVABILITY=0`, add zero required overhead.
    - If `CROSS_REPO_OBSERVABILITY=1`, capture monitored source list from
      `COMPATIBILITY_SOURCES` (`repo/module/contract/docs`) and include
      compatibility observability intent in handoff context.
-10. Optional component scope declaration (US-0035):
+11. Optional component scope declaration (US-0035):
    - If `COMPONENT_SCOPE_MODE=0`, add zero required scope overhead.
    - If `COMPONENT_SCOPE_MODE=1`, declare in-scope and out-of-scope components
      in `docs/engineering/component-scope.md` and include references in
      `handoffs/po_to_tl.md`.
-11. Optional spec-pack (US-0031):
+12. Optional spec-pack (US-0031):
    - If `SPEC_PACK_MODE=0`, add no required spec-pack steps (zero overhead).
    - If `SPEC_PACK_MODE=1`, ensure CRS artifact for the new story is created or
      updated at canonical path per runbook spec-pack contract; link story ID in
      handoff.
-12. Optional user-guide (US-0032):
+13. Optional user-guide (US-0032):
    - If `USER_GUIDE_MODE=0`, add no required user-guide steps or blocking checks (zero overhead).
    - If `USER_GUIDE_MODE=1`, ensure handoff references canonical user-guide path
      `docs/user-guides/US-xxxx.md` for the new story when applicable; see runbook.

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

@@ -108,4 +108,67 @@ verify no unresolved blockers.
    - If remote connectivity config is incomplete for required remote checks,
      mark blocking with deterministic reason code
      `REMOTE_CONNECTIVITY_CONFIG_INVALID`.
+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/release.md

@@ -96,6 +96,11 @@ Optional runbook keys (`LINT_COMMAND`, `TYPECHECK_COMMAND`) are not mandatory re
 
 Default: no bypass. Override only via explicit decision gate with documented rationale and evidence (see Override evidence contract below).
 
+## No-bypass default (US-0039)
+
+Release gates are mandatory by default. Bypass is not allowed unless an
+explicit decision gate is approved and evidence is recorded.
+
 Check-in test evidence: canonical source `tests/report.md`; valid = present + fresh + passing. Fail reasons: `RELEASE_TEST_EVIDENCE_MISSING`, `RELEASE_TEST_STALE`, `RELEASE_TEST_FAILED`. QA gate: no unresolved blocking findings; `RELEASE_QA_BLOCKERS_OPEN`, `RELEASE_QA_EVIDENCE_MISSING`. UAT gate: no placeholder/incomplete/unresolved-fail; `RELEASE_UAT_INCOMPLETE`, `RELEASE_UAT_FAILED`. Override evidence: decision record, rationale, approver, risk acceptance; `RELEASE_GATE_OVERRIDE_APPROVED`.
 
 ## QA completion evidence gate (US-0039)
@@ -106,6 +111,23 @@ Release may not proceed until QA completion evidence shows no unresolved blockin
 - **Pass condition**: No unresolved blocking or critical findings; QA phase has been run and findings recorded.
 - **Fail condition**: Unresolved blocking findings exist, or QA evidence is missing for target sprint — block with `RELEASE_QA_BLOCKERS_OPEN` or `RELEASE_QA_EVIDENCE_MISSING`; remediation: resolve blockers, re-run `/qa`, then rerun `/release`.
 
+## Generated-test evidence prerequisite (US-0066 / DEC-0048)
+
+For generated-project scope, release evidence must include deterministic
+generated-test auto-run references:
+
+- **Execution evidence source**: `sprints/Sxxxx/summary.md` generated baseline
+  test section (stack profile, generated paths, scaffold actions).
+- **QA evidence source**: `sprints/Sxxxx/qa-findings.md` generated-test auto-run
+  fields (`generated_test_command`, `generated_test_result`,
+  `generated_test_output_ref`, `generated_test_paths_ref`,
+  `generated_test_reason_code`).
+- **Pass condition**: generated-test evidence exists, is traceable, and does not
+  contradict QA/runtime verdicts.
+- **Fail condition**: missing/ambiguous generated-test evidence or unresolved
+  scaffold failure reason code; block release with
+  `TEST_SCAFFOLD_GENERATION_FAILED` and rerun `/execute` and/or `/qa`.
+
 ## UAT completion gate (US-0039)
 
 Release may not proceed until UAT artifacts are in verified state (no placeholder, incomplete, or unresolved-fail).
@@ -335,6 +357,37 @@ Guardrails:
       and local vs remote execution context.
     - In release output/handoffs, include operator connection guidance
       (where hosted, how to connect) without exposing secrets.
+18. Release operator Run/Connect/Verify hints contract (US-0067 / DEC-0049):
+    - `handoffs/releases/Sxxxx-release-notes.md` must include a deterministic
+      operator section order and required fields:
+      1) `## Run`:
+         - `start_command`
+         - `runtime_mode` (`local|remote`)
+         - `runtime_context_ref` (link to `docs/engineering/runtime-connectivity.md`
+           when available)
+      2) `## Connect`:
+         - `service_url`
+         - `service_port`
+         - `health_endpoint`
+      3) `## Verify`:
+         - `verification_steps` (deterministic numbered list)
+         - `expected_health_signal`
+      4) `## Credentials`:
+         - env-reference-only credential source refs (for example `API_TOKEN_ENV`)
+         - expected value source location guidance (for example CI secret store,
+           operator shell profile) with no inline secret values
+      5) `## Known Issues`:
+         - concise deterministic known issues list, or explicit `None`.
+    - `handoffs/release_notes.md` must include a concise latest release operator
+      summary (start command + endpoint + verify pointer) and link to canonical
+      sprint notes.
+    - Fail closed when required operator hints are missing/ambiguous or contain
+      inline secrets:
+      - `RELEASE_OPERATOR_HINTS_MISSING`
+      - `RELEASE_OPERATOR_HINTS_AMBIGUOUS`
+      - `RELEASE_OPERATOR_HINTS_SECRET_EXPOSURE`
+    - Remediation: populate required fields in canonical sprint notes with
+      sanitized env-ref-only credential guidance, then rerun `/release`.
 
 ## Fail-safe reason codes and remediation guidance
 
@@ -373,8 +426,14 @@ Required deterministic reason codes:
 - `PUBLISH_TARGET_EXECUTION_FAILED`
 - `REMOTE_CONNECTIVITY_CONFIG_INVALID`
 - `RUNTIME_CONNECTIVITY_DOC_WRITE_FAILED`
+- `RELEASE_OPERATOR_HINTS_MISSING`
+- `RELEASE_OPERATOR_HINTS_AMBIGUOUS`
+- `RELEASE_OPERATOR_HINTS_SECRET_EXPOSURE`
 - `PHASE_OWNERSHIP_VIOLATION`
 - `PHASE_OVERRIDE_EVIDENCE_MISSING`
+- `TEST_SCAFFOLD_STACK_UNRESOLVED`
+- `TEST_SCAFFOLD_UNSUPPORTED_STACK`
+- `TEST_SCAFFOLD_GENERATION_FAILED`
 
 When any reason code is emitted:
 - Preserve existing release note artifacts (non-destructive default).

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

@@ -82,6 +82,18 @@ Fail-closed behavior (no continuation):
 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.
+
 ## 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.
 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.

package/template/.cursor/rules/core.mdc

@@ -80,6 +80,16 @@ globs: ["**/*"]
   - 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.

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

@@ -32,4 +32,11 @@ globs: ["**/*"]
   `[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.
 

package/template/README.md

@@ -225,6 +225,37 @@ Intake runtime safety behavior (US-0059):
   writers; true conflicting external writes fail safe with
   `INTAKE_CONCURRENT_WRITER_DETECTED`.
 
+Runtime QA autopilot behavior (US-0065):
+- Generated-project QA must include runtime proof chain:
+  `startup -> readiness/connectivity -> log scan -> bounded retry -> verdict`.
+- Deterministic runtime fail codes:
+  `RUNTIME_STARTUP_FAILED`, `RUNTIME_ENDPOINT_UNREACHABLE`,
+  `RUNTIME_LOG_CRITICAL_DETECTED`, `RUNTIME_RETRY_BUDGET_EXHAUSTED`,
+  `RUNTIME_STACK_PROFILE_UNRESOLVED`.
+- Runtime evidence must include startup command/profile, runtime mode
+  (`local|remote`), health result, retry ledger, and log severity summary.
+- Stack-aware runtime profile resolution is required for Node/Python/Go/Java/.NET;
+  unresolved stacks fail closed (no generic silent PASS fallback).
+- For webapp contexts, QA includes browser-surface verification with
+  console/network error signals.
+
+Generated test scaffolding + auto-run behavior (US-0066):
+- `/execute` resolves stack profile (`node|python|go|java|dotnet`) and generates
+  missing baseline unit/integration/acceptance tests only.
+- Generation is non-destructive by default: preserve user-authored tests/config,
+  fill only missing baseline assets, keep reruns idempotent.
+- `TEST_COMMAND` wiring is deterministic:
+  - preserve existing non-empty user command,
+  - set stack baseline only when command is missing/unset.
+- `/qa` automatically runs the generated baseline tests and records deterministic
+  evidence (`command`, `result`, `output ref`, `generated paths ref`).
+- Fail-closed scaffold diagnostics:
+  `TEST_SCAFFOLD_STACK_UNRESOLVED`,
+  `TEST_SCAFFOLD_UNSUPPORTED_STACK`,
+  `TEST_SCAFFOLD_GENERATION_FAILED`.
+- Static baseline test pass does not bypass runtime autopilot; runtime verdict
+  remains mandatory for QA PASS.
+
 ## Workflow
 
 ### Core commands
@@ -277,6 +308,34 @@ broad/high-risk requests:
   (`docs/product/backlog.md`, `docs/product/acceptance.md`,
   `handoffs/po_to_tl.md`)
 
+### Mandatory intake question packs (US-0068)
+
+`/intake` now enforces deterministic minimum questionnaire packs before
+backlog/acceptance persistence:
+
+- `first-intake-pack` for first/new/broad requests
+- `small-intake-pack` for narrow follow-up requests
+
+Fail-closed coverage behavior:
+
+- required topic answers must be covered for the selected pack before write
+- unknown/ambiguous stack cues fail closed to `first-intake-pack`
+- persistence blocks with deterministic reason codes when required coverage is
+  incomplete and assumptions are not explicitly confirmed
+
+Deterministic reason codes:
+
+- `INTAKE_REQUIRED_TOPIC_MISSING`
+- `INTAKE_REQUIRED_PACK_INCOMPLETE`
+- `INTAKE_ASSUMPTION_CONFIRMATION_REQUIRED`
+- `INTAKE_PERSISTENCE_BLOCKED`
+
+Intake artifacts must persist coverage evidence fields:
+
+- `asked_topics`
+- `missing_topics`
+- `assumptions_confirmed`
+
 ### Optional ID namespace bootstrap (US-0052)
 
 Fresh-project ID bootstrap behavior is explicit and default-off:

package/template/docs/engineering/context/installer-owned-paths.manifest

@@ -17,6 +17,7 @@ decisions
 scripts/validate-and-push.ps1
 scripts/validate-and-push.sh
 .github/workflows
+README.md
 its_magic
 
 [clean_paths]

package/template/docs/engineering/runbook.md

@@ -101,6 +101,60 @@ decomposition and adaptive questioning behavior:
     `docs/product/backlog.md`, `docs/product/acceptance.md`, and
     `handoffs/po_to_tl.md`.
 
+## Mandatory intake question packs and persistence coverage gate (US-0068 / DEC-0050)
+
+Intake persistence is fail-closed unless required topic coverage is complete (or
+bounded assumptions are explicitly confirmed).
+
+Deterministic pack contract:
+
+- `first-intake-pack` (first/new/broad intake)
+  - required topics:
+    - `users_problem`
+    - `runtime_target_environment`
+    - `language_framework_runtime`
+    - `architecture_preference`
+    - `ui_design_expectations`
+    - `security_compliance`
+    - `non_functional_priorities`
+    - `scope_timeline`
+- `small-intake-pack` (small follow-up intake)
+  - required topics:
+    - `outcome_success_criteria`
+    - `impacted_components`
+    - `constraints_compatibility_risks`
+    - `required_tests_acceptance_checks`
+    - `done_definition`
+
+Pack selection and coverage behavior:
+
+- Select exactly one pack per intake write path.
+- Unknown/ambiguous stack or project cues must fail closed to
+  `first-intake-pack`.
+- Required coverage must be evaluated before writing
+  `docs/product/backlog.md` or `docs/product/acceptance.md`.
+- Incomplete required coverage blocks persistence unless assumptions are
+  explicitly confirmed.
+
+Deterministic fail-closed reason codes:
+
+- `INTAKE_REQUIRED_TOPIC_MISSING`
+- `INTAKE_REQUIRED_PACK_INCOMPLETE`
+- `INTAKE_ASSUMPTION_CONFIRMATION_REQUIRED`
+- `INTAKE_PERSISTENCE_BLOCKED`
+
+Required remediation output on block:
+
+- include `missing_topics`
+- provide targeted follow-up prompts for missing required topics
+- request explicit assumption confirmation when assumptions are used
+
+Required persisted intake evidence fields:
+
+- `asked_topics`
+- `missing_topics`
+- `assumptions_confirmed`
+
 ## Optional ID namespace bootstrap (US-0052)
 
 Fresh-project ID bootstrap is optional and default-off in
@@ -216,6 +270,34 @@ Safety contract:
 - Canonical operator endpoint summary is written to
   `docs/engineering/runtime-connectivity.md` with sanitized values only.
 
+## Release operator hints contract (US-0067 / DEC-0049)
+
+Release outputs must include deterministic operator-ready hints with mandatory
+section order:
+
+`Run -> Connect -> Verify -> Credentials -> Known Issues`
+
+Required fields for canonical sprint notes
+(`handoffs/releases/Sxxxx-release-notes.md`):
+
+- `Run`: `start_command`, `runtime_mode`, `runtime_context_ref`
+- `Connect`: `service_url`, `service_port`, `health_endpoint`
+- `Verify`: deterministic `verification_steps`, `expected_health_signal`
+- `Credentials`: env-reference-only source refs and expected value-source
+  location guidance (never inline secrets)
+- `Known Issues`: concise issue list or explicit `None`
+
+Legacy pointer contract (`handoffs/release_notes.md`):
+
+- keep concise latest run/connect/verify summary only
+- always link to canonical sprint-scoped release notes for full details
+
+Fail-closed reason codes:
+
+- `RELEASE_OPERATOR_HINTS_MISSING`
+- `RELEASE_OPERATOR_HINTS_AMBIGUOUS`
+- `RELEASE_OPERATOR_HINTS_SECRET_EXPOSURE`
+
 ## Deterministic status reconciliation mode (US-0055 / DEC-0037)
 
 Use the dedicated reconciliation command to normalize status drift across
@@ -474,6 +556,107 @@ Operator troubleshooting:
   - Replace with env-var reference fields (`tokenEnv`, `passwordEnv`,
     `privateKeyPathEnv`, ...).
 
+## Runtime QA autopilot contract (US-0065 / DEC-0047)
+
+Generated-project validation requires runtime proof, not static checks alone.
+
+Mandatory runtime stage order:
+
+`startup -> readiness/connectivity -> log scan -> bounded retry -> verdict`
+
+Deterministic runtime failure reason codes:
+
+- `RUNTIME_STARTUP_FAILED`
+- `RUNTIME_ENDPOINT_UNREACHABLE`
+- `RUNTIME_LOG_CRITICAL_DETECTED`
+- `RUNTIME_RETRY_BUDGET_EXHAUSTED`
+- `RUNTIME_STACK_PROFILE_UNRESOLVED`
+
+Runtime evidence schema (record in QA findings):
+
+- `runtime_startup_command`
+- `runtime_stack_profile` (`node|python|go|java|dotnet`)
+- `runtime_mode` (`local|remote`)
+- `runtime_health_target`
+- `runtime_health_result`
+- `runtime_log_summary` (severity counts and key error signals)
+- `runtime_retry_count`
+- `runtime_retry_ledger` (`attempt`, `delay_ms`, `outcome`)
+- `runtime_final_verdict`
+- `runtime_reason_code`
+- `runtime_evidence_refs`
+
+Bounded retry policy:
+
+- retry only transient startup/connectivity failures
+- enforce configured max-attempt cap (`attempt <= max`)
+- fail fast on non-transient critical runtime log signals
+
+Stack/profile resolution:
+
+- Minimum supported runtime profiles: Node, Python, Go, Java, .NET.
+- Unknown or ambiguous profile must fail closed with
+  `RUNTIME_STACK_PROFILE_UNRESOLVED`.
+
+Webapp verification path (when applicable):
+
+- include browser-surface load validation
+- capture console error summary and failed network request summary
+- add these signals to `runtime_log_summary` and evidence refs
+
+Optional debug escalation (bounded):
+
+- use for reproducible runtime failures only
+- keep instrumentation bounded and reversible
+- record applied debug steps and explicit cleanup confirmation
+
+## Generated test scaffolding + auto-run contract (US-0066 / DEC-0048)
+
+Generated app projects require deterministic baseline test scaffolding and
+automatic QA test execution evidence.
+
+Detection/profile contract:
+
+- Resolve one deterministic stack profile from:
+  `node|python|go|java|dotnet` (minimum supported).
+- If profile cannot be resolved, fail closed with
+  `TEST_SCAFFOLD_STACK_UNRESOLVED`.
+- If detected stack is outside supported baseline set, fail closed with
+  `TEST_SCAFFOLD_UNSUPPORTED_STACK`.
+
+Generation contract (`/execute`):
+
+- Generate only missing baseline assets for:
+  - unit tests
+  - integration tests
+  - acceptance tests
+- Use stable scaffold paths so reruns are idempotent (no duplicate file churn).
+- Record generated paths and actions in execution evidence.
+- If generation fails, fail closed with `TEST_SCAFFOLD_GENERATION_FAILED`.
+
+Runbook command wiring:
+
+- `TEST_COMMAND` baseline is stack-aware and deterministic.
+- Non-destructive precedence is mandatory:
+  - preserve user-authored non-empty `TEST_COMMAND`,
+  - write baseline command only when `TEST_COMMAND` is missing/unset.
+
+QA auto-run evidence contract (`/qa`):
+
+- Execute generated baseline tests automatically.
+- Record evidence fields:
+  - `generated_test_stack_profile`
+  - `generated_test_command`
+  - `generated_test_result`
+  - `generated_test_output_ref`
+  - `generated_test_paths_ref`
+  - `generated_test_reason_code`
+
+Runtime boundary with US-0065:
+
+- Generated static test PASS is required but never sufficient for QA PASS.
+- Runtime-autopilot verdict remains mandatory; non-starting apps cannot PASS QA.
+
 ## Auto continuation resume contract
 
 `/auto` continuation uses deterministic phase resolution (DEC-0017):

package/template/handoffs/release_notes.md

@@ -23,6 +23,19 @@ Canonical queue state now lives under:
 Check `handoffs/release_queue.md` for all pending entries where `status=unreleased`
 or `status=blocked` before finalization.
 
+## Latest operator summary (Run/Connect/Verify)
+
+- **Start command:** Refer to `## Run` in
+  `handoffs/releases/Sxxxx-release-notes.md`.
+- **Endpoint + port:** Refer to `## Connect` in
+  `handoffs/releases/Sxxxx-release-notes.md`.
+- **Verification steps + health signal:** Refer to `## Verify` in
+  `handoffs/releases/Sxxxx-release-notes.md`.
+- **Credentials source refs (sanitized):** Refer to `## Credentials` in
+  `handoffs/releases/Sxxxx-release-notes.md` (env-ref only).
+- **Known issues:** Refer to `## Known Issues` in
+  `handoffs/releases/Sxxxx-release-notes.md`.
+
 ## Historical references
 
 - `Sxxxx`: `handoffs/releases/Sxxxx-release-notes.md`

package/template/handoffs/releases/Sxxxx-release-notes.md

@@ -16,10 +16,45 @@
 
 ---
 
+## Run
+
+- `start_command`: `<required>`
+- `runtime_mode`: `local|remote` (required)
+- `runtime_context_ref`: `docs/engineering/runtime-connectivity.md` (required
+  when present)
+
+## Connect
+
+- `service_url`: `<required>`
+- `service_port`: `<required>`
+- `health_endpoint`: `<required>`
+
+## Verify
+
+- `verification_steps`:
+  1. `<required step 1>`
+  2. `<required step 2>`
+  3. `<required step 3>`
+- `expected_health_signal`: `<required>`
+
+## Credentials
+
+- `credential_source_refs` (env names only):
+  - `<ENV_VAR_NAME>`
+- `expected_value_source`:
+  - `<CI secret store | operator shell profile | deployment platform variable set>`
+- Never place inline secrets/tokens/passwords in this file.
+
+## Known Issues
+
+- `None` or deterministic concise issue list.
+
 ## Notes
 
 - Sprint-scoped notes are canonical history artifacts.
 - Do not overwrite notes for non-target sprints.
+- Required section order is deterministic:
+  `Run -> Connect -> Verify -> Credentials -> Known Issues`.
 
 ## Queue linkage