its-magic 0.1.2-21 → 0.1.2-22

package/README.md

@@ -199,6 +199,18 @@ Setup:
 2. Set personal values there (`TEAM_MEMBER`, `ACTIVE_TASK_IDS`, automation style)
 3. Hook merges shared + local (local wins)
 
+Upgrade behavior (US-0057):
+- `.cursor/scratchpad.local.example.md` is framework-owned and refreshed on `--mode upgrade`.
+- `.cursor/scratchpad.local.md` is user-owned and preserved on `--mode upgrade`.
+- Installer output includes scratchpad example refresh status and local-preserved signal.
+
+Deterministic ordering behavior (US-0058):
+- Mutable artifacts follow `docs/engineering/artifact-ordering-policy.md`.
+- `state.md` checkpoints are append-bottom; `backlog.md` and `acceptance.md`
+  remain sorted-canonical by story ID.
+- Commands fail closed on ambiguous placement anchors using
+  `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS`.
+
 ## Workflow
 
 ### Core commands
@@ -303,6 +315,41 @@ Compaction behavior:
 - bounded expansion only when unresolved
 - explicit "not found in artifacts" when still unresolved
 
+### Configurable multi-target publish + confirmation gate (US-0054)
+
+Post-release publish behavior is configurable per repository:
+
+- `RELEASE_PUBLISH_MODE=disabled|confirm|auto` (default `confirm`)
+- `RELEASE_TARGETS_FILE=docs/engineering/release-targets.json`
+- `RELEASE_TARGETS_DEFAULT=` optional comma-separated default targets
+
+Supported target types include:
+
+- `npm`, `choco`, `brew`, `git`, `docker`, `cloud`
+- `custom` (generic command target)
+- `ssh` (generic server deployment over SSH)
+
+Safety defaults:
+
+- Mandatory `/release` gates are unchanged and must pass first.
+- `confirm` mode enforces explicit operator approval before publish execution.
+- Sensitive values are env-referenced (for example `tokenEnv`, `authEnv`), not
+  inline literals.
+
+### Deterministic status reconciliation command (US-0055)
+
+Use `/status-reconcile` to normalize status drift between canonical and derived
+workflow artifacts before continuation:
+
+- canonical source: `docs/product/backlog.md` story status
+- derived targets: `docs/product/acceptance.md`, `docs/engineering/state.md`,
+  `handoffs/resume_brief.md`
+- deterministic outcomes: apply/no-op/fail-safe reason codes with audit evidence
+  in `docs/engineering/status-normalization-report.md`
+
+This command is the bounded repair counterpart to `/memory-audit`
+(read-only detection).
+
 ### Optional cross-repo observability (US-0034)
 
 Use optional compatibility visibility with default-safe off behavior:
@@ -454,6 +501,21 @@ Missing/invalid/stale evidence fails closed with reason codes:
 `PHASE_CONTEXT_ISOLATION_MISSING`, `PHASE_CONTEXT_ISOLATION_VIOLATION`,
 `ISOLATION_EVIDENCE_STALE`, `ISOLATION_EVIDENCE_INVALID`.
 
+#### Strict runtime proof (US-0056 / DEC-0038)
+
+Per-phase isolation also requires strict runtime attestation tuples at
+boundaries (not artifact fields alone):
+
+- `orchestrator_run_id`, `runtime_proof_id`, `phase_id`, `role`
+- `proof_issued_at`, `proof_ttl_seconds`, `proof_hash`
+
+Fail-closed reason codes:
+`RUNTIME_PROOF_MISSING`, `RUNTIME_PROOF_INVALID`, `RUNTIME_PROOF_REUSED`,
+`RUNTIME_PROOF_STALE`, `RUNTIME_PROOF_AMBIGUOUS_LINK`.
+
+`/auto`, `/verify-work`, and `/release` must validate these tuples before
+continuation/finalization.
+
 ### Lightweight interaction
 
 Use `/ask` when you want to query the project without triggering the workflow:

package/installer.ps1

@@ -372,6 +372,8 @@ if ($mode -eq "upgrade") {
   $unchanged = 0
   $preserved = 0
   $review = New-Object System.Collections.Generic.List[string]
+  $scratchpadExampleRel = '.cursor/scratchpad.local.example.md'
+  $scratchpadExampleStatus = 'not-seen'
 
   foreach ($rel in $files) {
     $src = Join-Path $sourceRoot $rel
@@ -383,16 +385,19 @@ if ($mode -eq "upgrade") {
       Ensure-Parent $dst
       Copy-Item -Path $src -Destination $dst -Force
       $added.Add($rel)
+      if ($rel -eq $scratchpadExampleRel) { $scratchpadExampleStatus = 'added' }
       continue
     }
 
     if ($cat -eq 'framework') {
       if (Files-ContentEqual $src $dst) {
         $unchanged++
+        if ($rel -eq $scratchpadExampleRel) { $scratchpadExampleStatus = 'unchanged' }
       } else {
         Ensure-Parent $dst
         Copy-Item -Path $src -Destination $dst -Force
         $updated.Add($rel)
+        if ($rel -eq $scratchpadExampleRel) { $scratchpadExampleStatus = 'updated' }
       }
       continue
     }
@@ -426,6 +431,11 @@ if ($mode -eq "upgrade") {
   }
   Write-Host "  Unchanged:           $unchanged files"
   Write-Host "  Preserved (user):    $preserved files"
+  if ($scratchpadExampleStatus -eq 'not-seen') { $scratchpadExampleStatus = 'not-in-manifest' }
+  Write-Host "  Scratchpad example:  $scratchpadExampleStatus (.cursor/scratchpad.local.example.md)"
+  if (Test-Path (Join-Path $targetRoot '.cursor/scratchpad.local.md') -PathType Leaf) {
+    Write-Host "  User local file:     preserved (.cursor/scratchpad.local.md)"
+  }
   if ($review.Count -gt 0) {
     Write-Host ""
     Write-Host "  Review recommended:  $($review.Count) files" -ForegroundColor Magenta

package/installer.py

@@ -333,6 +333,8 @@ def main():
 
         added, updated, review = [], [], []
         unchanged = preserved = 0
+        scratchpad_example_rel = ".cursor/scratchpad.local.example.md"
+        scratchpad_example_status = "not-seen"
 
         for rel in files:
             src = os.path.join(source_root, rel)
@@ -344,15 +346,21 @@ def main():
                 ensure_parent(dst)
                 shutil.copy2(src, dst)
                 added.append(rel)
+                if rel == scratchpad_example_rel:
+                    scratchpad_example_status = "added"
                 continue
 
             if cat == "framework":
                 if filecmp.cmp(src, dst, shallow=False):
                     unchanged += 1
+                    if rel == scratchpad_example_rel:
+                        scratchpad_example_status = "unchanged"
                 else:
                     ensure_parent(dst)
                     shutil.copy2(src, dst)
                     updated.append(rel)
+                    if rel == scratchpad_example_rel:
+                        scratchpad_example_status = "updated"
                 continue
 
             if cat == "user-data":
@@ -384,6 +392,11 @@ def main():
                 print(f"    {f}")
         print(f"  Unchanged:           {unchanged} files")
         print(f"  Preserved (user):    {preserved} files")
+        if scratchpad_example_status == "not-seen":
+            scratchpad_example_status = "not-in-manifest"
+        print(f"  Scratchpad example:  {scratchpad_example_status} (.cursor/scratchpad.local.example.md)")
+        if os.path.isfile(os.path.join(target_root, ".cursor", "scratchpad.local.md")):
+            print("  User local file:     preserved (.cursor/scratchpad.local.md)")
         if review:
             print(f"\n  {p}Review recommended:  {len(review)} files{r}")
             for f in review:

package/installer.sh

@@ -322,6 +322,8 @@ if [ "$MODE" = "upgrade" ]; then
   count_unchanged=0
   count_preserved=0
   count_review=0; list_review=""
+  scratchpad_example_rel=".cursor/scratchpad.local.example.md"
+  scratchpad_example_status="not-seen"
 
   for rel in $FILES; do
     src="$SOURCE_ROOT/$rel"
@@ -333,17 +335,20 @@ if [ "$MODE" = "upgrade" ]; then
       cp -p "$src" "$dst"
       count_added=$((count_added + 1))
       list_added="$list_added $rel"
+      [ "$rel" = "$scratchpad_example_rel" ] && scratchpad_example_status="added"
       continue
     fi
 
     if [ "$cat" = "framework" ]; then
       if cmp -s "$src" "$dst"; then
         count_unchanged=$((count_unchanged + 1))
+        [ "$rel" = "$scratchpad_example_rel" ] && scratchpad_example_status="unchanged"
       else
         ensure_parent "$dst"
         cp -p "$src" "$dst"
         count_updated=$((count_updated + 1))
         list_updated="$list_updated $rel"
+        [ "$rel" = "$scratchpad_example_rel" ] && scratchpad_example_status="updated"
       fi
       continue
     fi
@@ -377,6 +382,9 @@ if [ "$MODE" = "upgrade" ]; then
   fi
   printf "  Unchanged:           %s files\n" "$count_unchanged"
   printf "  Preserved (user):    %s files\n" "$count_preserved"
+  [ "$scratchpad_example_status" = "not-seen" ] && scratchpad_example_status="not-in-manifest"
+  printf "  Scratchpad example:  %s (.cursor/scratchpad.local.example.md)\n" "$scratchpad_example_status"
+  [ -f "$TARGET_ROOT/.cursor/scratchpad.local.md" ] && printf "  User local file:     preserved (.cursor/scratchpad.local.md)\n"
   if [ "$count_review" -gt 0 ]; then
     printf "\n  \033[1;35mReview recommended:  %s files\033[0m\n" "$count_review"
     for f in $list_review; do printf "    %s\n" "$f"; done

package/package.json

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

package/template/.cursor/commands/auto.md

@@ -35,6 +35,32 @@ Reason codes (deterministic):
 - `ISOLATION_EVIDENCE_STALE`
 - `ISOLATION_EVIDENCE_INVALID`
 
+## Strict runtime proof enforcement (US-0056 / DEC-0038)
+
+`/auto` must enforce strict runtime attestation in addition to artifact-level
+isolation evidence:
+
+- Each completed phase must provide a runtime attestation tuple linked to the
+  phase checkpoint evidence:
+  - `orchestrator_run_id`
+  - `runtime_proof_id`
+  - `phase_id`
+  - `role`
+  - `proof_issued_at` (ISO UTC / RFC3339)
+  - `proof_ttl_seconds`
+  - `proof_hash`
+- `runtime_proof_id` must be unique per phase run; reused proof IDs are invalid.
+- Proof freshness must be validated against `proof_issued_at` + TTL policy.
+- Proof linkage must be deterministic and auditable to checkpoint evidence refs.
+- Fail closed on any strict-proof violation; no silent continuation.
+
+Strict-proof reason codes:
+- `RUNTIME_PROOF_MISSING`
+- `RUNTIME_PROOF_INVALID`
+- `RUNTIME_PROOF_REUSED`
+- `RUNTIME_PROOF_STALE`
+- `RUNTIME_PROOF_AMBIGUOUS_LINK`
+
 ## Inputs
 - `AUTO_FLOW_MODE` and `PHASE_MODE` from `.cursor/scratchpad.md`
 - `AUTO_IMPLEMENTATION_LOOP`, `AUTO_LOOP_MAX_CYCLES` from `.cursor/scratchpad.md`
@@ -194,6 +220,11 @@ Reason-code baseline:
 - `EXEC_BULK_NO_ELIGIBLE_ITEMS`
 - `EXEC_TEAM_SCOPE_BLOCKED`
 - `EXEC_TEAM_SCOPE_SKIPPED`
+- `RUNTIME_PROOF_MISSING`
+- `RUNTIME_PROOF_INVALID`
+- `RUNTIME_PROOF_REUSED`
+- `RUNTIME_PROOF_STALE`
+- `RUNTIME_PROOF_AMBIGUOUS_LINK`
 
 ## Canonical `start-from` contract
 
@@ -308,6 +339,17 @@ Required codes:
     missing/invalid/stale, stop with the appropriate reason code and remediation
     guidance (run the phase again in a fresh subagent context and write new
     evidence).
+11b. At each phase boundary, verify strict runtime attestation tuple exists and
+    is valid for the completed phase (`orchestrator_run_id`,
+    `runtime_proof_id`, `phase_id`, `role`, `proof_issued_at`,
+    `proof_ttl_seconds`, `proof_hash`).
+    - Missing tuple: `RUNTIME_PROOF_MISSING`
+    - Invalid schema/hash/linkage: `RUNTIME_PROOF_INVALID`
+    - Reused `runtime_proof_id`: `RUNTIME_PROOF_REUSED`
+    - Expired proof TTL / stale proof: `RUNTIME_PROOF_STALE`
+    - Ambiguous proof-to-checkpoint linkage: `RUNTIME_PROOF_AMBIGUOUS_LINK`
+    - Remediation: rerun affected phase in fresh subagent context, write new
+      strict-proof tuple + checkpoint evidence, then continue.
 12. At each phase boundary, evaluate sync policy only when mode requires it and
     record a deterministic sync verdict entry with:
     - `phase_boundary`
@@ -338,3 +380,14 @@ Required codes:
 - `/resume` remains valid for context loading and guided continuation.
 - Deterministic precedence and fail-fast behavior apply when `/auto` continuation
   is invoked.
+
+## Deterministic artifact ordering guard (US-0058 / DEC-0040)
+
+- When `/auto` coordinates phases that write mutable artifacts, each phase must
+  follow `docs/engineering/artifact-ordering-policy.md`.
+- Ordering policies are mandatory:
+  - `state.md`: append-bottom
+  - `backlog.md` / `acceptance.md`: sorted-canonical
+  - release/handoff surfaces: policy-specific (prepend/append) as documented.
+- If a required placement anchor is missing or ambiguous, fail closed with
+  `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS` and do not continue.

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

@@ -118,3 +118,15 @@ description: "its-magic intake: clarify idea and capture story + acceptance."
    - 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.
 
+## Deterministic artifact ordering contract (US-0058 / DEC-0040)
+
+- Writes to mutable artifacts must follow
+  `docs/engineering/artifact-ordering-policy.md`.
+- For intake outputs:
+  - `docs/product/backlog.md` story blocks must remain sorted-canonical by
+    numeric `US-xxxx` ID.
+  - `docs/product/acceptance.md` rows must align to canonical backlog order.
+  - `handoffs/po_to_tl.md` may prepend the latest handoff section only.
+- If the insertion anchor for any target section is missing/ambiguous, fail with
+  `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS` and avoid partial writes.
+

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

@@ -28,3 +28,14 @@ description: "its-magic refresh context: compact state and decisions."
 2. Update sprint summary with current status.
 3. Ensure handoffs and state are consistent.
 
+## 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).
+

package/template/.cursor/commands/release.md

@@ -89,6 +89,7 @@ Mandatory gate order (strict, deterministic). No step may be skipped or reordere
 2. **QA completion gate** — Require no unresolved blocking findings in current sprint context before proceeding.
 3. **UAT completion gate** — Require UAT artifacts populated and verified; block on placeholder, incomplete, or unresolved-fail state.
 4. **Isolation compliance gate** — Require valid per-phase isolation evidence (US-0048 / DEC-0029); block on missing/invalid/stale evidence or violation.
+4b. **Strict runtime proof gate** — Require valid strict runtime attestation tuples (US-0056 / DEC-0038); block on missing/invalid/reused/stale/ambiguous proof linkage.
 5. **Release finalization** — Only after gates 1–4 pass: write release notes, update queue, reconcile backlog/runbook/state.
 
 Optional runbook keys (`LINT_COMMAND`, `TYPECHECK_COMMAND`) are not mandatory release gates. When blank, they must not cause release to fail; report as `skipped`. Mandatory gates remain check-in test + QA + UAT + isolation only (US-0039 AC-10, US-0048).
@@ -234,6 +235,17 @@ Guardrails:
       `PHASE_CONTEXT_ISOLATION_VIOLATION`
     - Remediation: re-run the affected phase(s) in fresh subagent contexts,
       write new isolation evidence, then rerun `/release`.
+4b. Strict runtime proof gate (US-0056 / DEC-0038): verify strict runtime-proof
+    tuples are present and valid for target lifecycle phases (`execute`, `qa`,
+    `verify-work`) and deterministically linked to checkpoint evidence.
+    - Missing tuple: block with `RUNTIME_PROOF_MISSING`
+    - Invalid tuple/hash/linkage: block with `RUNTIME_PROOF_INVALID`
+    - Reused `runtime_proof_id`: block with `RUNTIME_PROOF_REUSED`
+    - Expired/stale proof: block with `RUNTIME_PROOF_STALE`
+    - Ambiguous proof-to-checkpoint linkage: block with
+      `RUNTIME_PROOF_AMBIGUOUS_LINK`
+    - Remediation: rerun affected phase(s), write fresh runtime proof tuples,
+      then rerun `/release`.
 5. Ensure target queue row exists; set status to `unreleased` before finalization.
    - Create row if missing.
    - Set `release_notes_ref` to target sprint notes path.
@@ -284,6 +296,30 @@ Guardrails:
       (`PASS`) and references final evidence artifacts.
 15. If `AUTO_RELEASE_NOTES=1` in `.cursor/scratchpad.md`, generation logic must
     still target sprint-scoped notes first and update legacy pointer second.
+16. Optional configurable publish targets (US-0054 / DEC-0036):
+    - Read `.cursor/scratchpad.md`:
+      - `RELEASE_PUBLISH_MODE=disabled|confirm|auto`
+      - `RELEASE_TARGETS_FILE`
+      - `RELEASE_TARGETS_DEFAULT`
+    - If `RELEASE_PUBLISH_MODE=disabled`, skip publish target execution with
+      deterministic no-op evidence.
+    - Validate target schema in `RELEASE_TARGETS_FILE` before execution:
+      - stable `id`, `type`, `enabled`, `order`,
+      - supported `type`: `npm|choco|brew|git|docker|cloud|custom|ssh`,
+      - env-reference-only secret fields (`*Env`) for sensitive values.
+      - fail fast on invalid/missing required fields with
+        `PUBLISH_TARGET_CONFIG_INVALID`.
+    - Resolve selected targets (explicit request, else
+      `RELEASE_TARGETS_DEFAULT`), filter `enabled=true`, and execute in
+      deterministic order (`order`, then `id`).
+    - If `RELEASE_PUBLISH_MODE=confirm`, require explicit operator confirmation
+      before execution; if confirmation is denied/absent, stop with
+      `PUBLISH_CONFIRMATION_REQUIRED`.
+    - For `ssh` targets, require `hostEnv`, `userEnv`, `authEnv`, and
+      `remoteCommand`. Missing required fields fail with
+      `PUBLISH_TARGET_CONFIG_INVALID`.
+    - If target execution fails, emit `PUBLISH_TARGET_EXECUTION_FAILED` with
+      target ID and remediation; do not mutate unrelated release artifacts.
 
 ## Fail-safe reason codes and remediation guidance
 
@@ -298,6 +334,11 @@ Required deterministic reason codes:
 - `PHASE_CONTEXT_ISOLATION_VIOLATION`
 - `ISOLATION_EVIDENCE_STALE`
 - `ISOLATION_EVIDENCE_INVALID`
+- `RUNTIME_PROOF_MISSING`
+- `RUNTIME_PROOF_INVALID`
+- `RUNTIME_PROOF_REUSED`
+- `RUNTIME_PROOF_STALE`
+- `RUNTIME_PROOF_AMBIGUOUS_LINK`
 - `RELEASE_GATE_OVERRIDE_APPROVED`
 - `LEGACY_NOTES_SPRINT_UNRESOLVED`
 - `QUEUE_ENTRY_MISSING`
@@ -312,9 +353,27 @@ Required deterministic reason codes:
 - `BACKLOG_DONE_ACCEPTANCE_UNCHECKED`
 - `BACKLOG_DONE_TRACEABILITY_MISSING`
 - `BACKLOG_DONE_RELEASE_ARTIFACT_MISSING`
+- `PUBLISH_TARGET_CONFIG_INVALID`
+- `PUBLISH_CONFIRMATION_REQUIRED`
+- `PUBLISH_TARGET_EXECUTION_FAILED`
 
 When any reason code is emitted:
 - Preserve existing release note artifacts (non-destructive default).
 - Do not auto-reconcile by deleting/rebuilding unrelated sprint history.
 - Provide actionable remediation steps and require rerun after correction.
 
+## Deterministic artifact ordering contract (US-0058 / DEC-0040)
+
+- Mutations in `/release` must comply with
+  `docs/engineering/artifact-ordering-policy.md`.
+- Ordering expectations:
+  - `docs/engineering/state.md`: append-bottom checkpoint entries only.
+  - `docs/product/backlog.md` + `docs/product/acceptance.md`: target story
+    normalization while preserving sorted-canonical order.
+  - `handoffs/release_queue.md`: append one target sprint row/update in-place for
+    that row only.
+  - `handoffs/release_notes.md`: update latest pointer section first; keep
+    historical list stable.
+- Missing/ambiguous placement anchors must fail with
+  `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS` and no partial mutation.
+

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

@@ -0,0 +1,90 @@
+---
+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
+- `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.
+- `docs/product/acceptance.md` and `docs/engineering/state.md` are derived views.
+- Reconciliation must not infer canonical story status from derived artifacts.
+
+## 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

@@ -66,6 +66,22 @@ 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.
+
 ## 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/scratchpad.local.example.md

@@ -1,42 +1,83 @@
 # its-magic scratchpad (local overrides example)
 #
-# Copy this file to `.cursor/scratchpad.local.md` and set your personal values.
-# This file is intended to stay local and is gitignored.
+# Copy this file to `.cursor/scratchpad.local.md` and set personal overrides.
+# Local values override `.cursor/scratchpad.md` and should stay gitignored.
 #
-# Team identity / ownership
-# - TEAM_MODE: 0|1
-# - TEAM_MEMBER: short id for current developer
-# - ACTIVE_TASK_IDS: comma-separated task ids (for example T-12,T-13)
-TEAM_MODE=0
-TEAM_MEMBER=
-ACTIVE_TASK_IDS=
-#
-# Personal automation style
-# - PHASE_MODE: interactive|auto
-# - PERMISSION_MODE: interactive|auto
-# - RUN_TESTS_ON_EDIT: 0|1
-# - LOOP_UNTIL_GREEN: 0|1
-# - AUTO_IMPLEMENTATION_LOOP: 0|1
-# - AUTO_LOOP_MAX_CYCLES: integer >= 1
-# - AUTO_PAUSE_POLICY: after_task|after_phase
-PHASE_MODE=interactive
-PERMISSION_MODE=interactive
-RUN_TESTS_ON_EDIT=0
+# Core behavior
+MAGIC_CONTEXT_STRICT=1
 LOOP_UNTIL_GREEN=0
+RUN_TESTS_ON_EDIT=0
 AUTO_IMPLEMENTATION_LOOP=0
 AUTO_LOOP_MAX_CYCLES=5
+AUTO_PAUSE_REQUEST=0
 AUTO_PAUSE_POLICY=after_phase
+DONE=0
+#
+# Benchmarking
+MAGIC_BENCH_SESSION=
+#
+# Automation
+AUTO_FLOW_MODE=auto_until_decision
+PHASE_MODE=interactive
+PERMISSION_MODE=interactive
+AUTO_INSTALL_DEPS=0
+AUTO_RELEASE_NOTES=1
+AUTO_BACKLOG_DRAIN=0
+AUTO_BACKLOG_MAX_STORIES=1
+AUTO_BACKLOG_ON_BLOCK=stop
+AUTO_STORY_SELECTION=priority_then_backlog_order
+AUTO_EXECUTE_BULK=0
+AUTO_EXECUTE_MAX_ITEMS=1
+AUTO_EXECUTE_ON_BLOCK=stop
+AUTO_EXECUTE_SELECTION=planned_then_priority
+AUTO_TEAM_SCOPE_ENFORCE=1
 #
-# Sprint planning (override team defaults)
-# - SPRINT_MAX_TASKS: integer >= 1 (max atomic tasks per sprint)
-# - SPRINT_AUTO_SPLIT: 0|1 (propose splitting when over threshold)
+# Team mode
+TEAM_MODE=0
+TEAM_MEMBER=
+ACTIVE_TASK_IDS=
+#
+# Sprint planning
 SPRINT_MAX_TASKS=12
 SPRINT_AUTO_SPLIT=1
+SPRINT_BULK_MAX_STORIES=5
+SPRINT_BULK_MAX_SPRINTS=3
+SPRINT_BULK_SELECTION=priority_then_backlog_order
 #
-# Personal environment preferences
-# - AUTO_INSTALL_DEPS: 0|1
-# - REMOTE_EXECUTION: 0|1
-# - REMOTE_CONFIG: path to your local remote config
-AUTO_INSTALL_DEPS=0
+# Remote execution
 REMOTE_EXECUTION=0
 REMOTE_CONFIG=.cursor/remote.json
+#
+# Sync policy
+SYNC_POLICY_MODE=manual
+SYNC_CUSTOM_PHASES=
+ALLOW_AUTO_PUSH=0
+AUTO_PUSH_BRANCH_ALLOWLIST=
+#
+# Knowledge curation / intake
+EARLY_RESEARCH=1
+INTAKE_GUIDED_MODE=1
+ID_NAMESPACE_BOOTSTRAP=0
+TOKEN_PROFILE=balanced
+#
+# Publish targets
+RELEASE_PUBLISH_MODE=confirm
+RELEASE_TARGETS_FILE=docs/engineering/release-targets.json
+RELEASE_TARGETS_DEFAULT=
+#
+# Security review
+SECURITY_REVIEW=0
+COMPLIANCE_PROFILES=GDPR
+#
+# Compatibility observability
+CROSS_REPO_OBSERVABILITY=0
+COMPATIBILITY_GATE_ON_CRITICAL=1
+COMPATIBILITY_SOURCES=
+#
+# Component scope
+COMPONENT_SCOPE_MODE=0
+TARGET_COMPONENTS=
+#
+# Optional docs packs
+SPEC_PACK_MODE=0
+USER_GUIDE_MODE=0

package/template/.cursor/scratchpad.md

@@ -101,6 +101,17 @@ INTAKE_GUIDED_MODE=1
 ID_NAMESPACE_BOOTSTRAP=0
 TOKEN_PROFILE=balanced
 
+# Publish targets (US-0054)
+# - RELEASE_PUBLISH_MODE: disabled|confirm|auto
+#   - disabled: skip post-release publish target execution
+#   - confirm: require explicit operator confirmation before publish (default)
+#   - auto: allow publish without confirmation (explicit opt-in)
+# - RELEASE_TARGETS_FILE: canonical target config path
+# - RELEASE_TARGETS_DEFAULT: comma-separated default target IDs (optional)
+RELEASE_PUBLISH_MODE=confirm
+RELEASE_TARGETS_FILE=docs/engineering/release-targets.json
+RELEASE_TARGETS_DEFAULT=
+
 #
 # Security review
 # - SECURITY_REVIEW: 0|1 (enable optional security/compliance review; default off)

package/template/README.md

@@ -199,6 +199,18 @@ Setup:
 2. Set personal values there (`TEAM_MEMBER`, `ACTIVE_TASK_IDS`, automation style)
 3. Hook merges shared + local (local wins)
 
+Upgrade behavior (US-0057):
+- `.cursor/scratchpad.local.example.md` is framework-owned and refreshed on `--mode upgrade`.
+- `.cursor/scratchpad.local.md` is user-owned and preserved on `--mode upgrade`.
+- Installer output includes scratchpad example refresh status and local-preserved signal.
+
+Deterministic ordering behavior (US-0058):
+- Mutable artifacts follow `docs/engineering/artifact-ordering-policy.md`.
+- `state.md` checkpoints are append-bottom; `backlog.md` and `acceptance.md`
+  remain sorted-canonical by story ID.
+- Commands fail closed on ambiguous placement anchors using
+  `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS`.
+
 ## Workflow
 
 ### Core commands
@@ -303,6 +315,41 @@ Compaction behavior:
 - bounded expansion only when unresolved
 - explicit "not found in artifacts" when still unresolved
 
+### Configurable multi-target publish + confirmation gate (US-0054)
+
+Post-release publish behavior is configurable per repository:
+
+- `RELEASE_PUBLISH_MODE=disabled|confirm|auto` (default `confirm`)
+- `RELEASE_TARGETS_FILE=docs/engineering/release-targets.json`
+- `RELEASE_TARGETS_DEFAULT=` optional comma-separated default targets
+
+Supported target types include:
+
+- `npm`, `choco`, `brew`, `git`, `docker`, `cloud`
+- `custom` (generic command target)
+- `ssh` (generic server deployment over SSH)
+
+Safety defaults:
+
+- Mandatory `/release` gates are unchanged and must pass first.
+- `confirm` mode enforces explicit operator approval before publish execution.
+- Sensitive values are env-referenced (for example `tokenEnv`, `authEnv`), not
+  inline literals.
+
+### Deterministic status reconciliation command (US-0055)
+
+Use `/status-reconcile` to normalize status drift between canonical and derived
+workflow artifacts before continuation:
+
+- canonical source: `docs/product/backlog.md` story status
+- derived targets: `docs/product/acceptance.md`, `docs/engineering/state.md`,
+  `handoffs/resume_brief.md`
+- deterministic outcomes: apply/no-op/fail-safe reason codes with audit evidence
+  in `docs/engineering/status-normalization-report.md`
+
+This command is the bounded repair counterpart to `/memory-audit`
+(read-only detection).
+
 ### Optional cross-repo observability (US-0034)
 
 Use optional compatibility visibility with default-safe off behavior:
@@ -456,6 +503,21 @@ Missing/invalid/stale evidence fails closed with reason codes:
 `PHASE_CONTEXT_ISOLATION_MISSING`, `PHASE_CONTEXT_ISOLATION_VIOLATION`,
 `ISOLATION_EVIDENCE_STALE`, `ISOLATION_EVIDENCE_INVALID`.
 
+#### Strict runtime proof (US-0056 / DEC-0038)
+
+Per-phase isolation also requires strict runtime attestation tuples at
+boundaries (not artifact fields alone):
+
+- `orchestrator_run_id`, `runtime_proof_id`, `phase_id`, `role`
+- `proof_issued_at`, `proof_ttl_seconds`, `proof_hash`
+
+Fail-closed reason codes:
+`RUNTIME_PROOF_MISSING`, `RUNTIME_PROOF_INVALID`, `RUNTIME_PROOF_REUSED`,
+`RUNTIME_PROOF_STALE`, `RUNTIME_PROOF_AMBIGUOUS_LINK`.
+
+`/auto`, `/verify-work`, and `/release` must validate these tuples before
+continuation/finalization.
+
 ### Lightweight interaction
 
 Use `/ask` when you want to query the project without triggering the workflow:

package/template/docs/engineering/artifact-ordering-policy.md

@@ -0,0 +1,29 @@
+# Artifact Ordering Policy (US-0058 / DEC-0040)
+
+This policy defines deterministic write order for mutable workflow artifacts.
+Commands that mutate these artifacts must use this matrix and fail safe when
+anchors are missing or ambiguous.
+
+## Canonical matrix
+
+| Artifact | Policy | Deterministic rule |
+|---|---|---|
+| `docs/engineering/state.md` | `append-bottom` | Add new checkpoints only at end of file, in chronological order. |
+| `docs/product/backlog.md` | `sorted-canonical` | Keep stories sorted by numeric `US-xxxx` ID; mutate only target story block. |
+| `docs/product/acceptance.md` | `sorted-canonical` | Keep `US-xxxx` rows ordered by numeric ID aligned to backlog order. |
+| `handoffs/release_queue.md` | `append-bottom` | Append only one row per new sprint in release order. |
+| `handoffs/release_notes.md` | `prepend-top` | Update latest pointer section first; preserve historical references list. |
+| `handoffs/resume_brief.md` | `prepend-top` | Update current status/next-actions sections without rewriting unrelated history. |
+
+## Idempotence contract
+
+- Re-running a command without semantic changes must not reorder rows/blocks.
+- No oscillation between top and bottom insertion paths.
+- No broad rewrites of unrelated story/sprint entries.
+
+## Fail-safe behavior
+
+If required placement anchors are missing or ambiguous:
+- stop with reason code `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS`,
+- emit remediation guidance with expected anchor and file path,
+- perform no partial mutation.

package/template/docs/engineering/release-targets.json

@@ -0,0 +1,64 @@
+{
+  "version": 1,
+  "selectionPolicy": "explicit_or_default",
+  "targets": [
+    {
+      "id": "npm-public",
+      "type": "npm",
+      "enabled": false,
+      "order": 10,
+      "command": "npm publish",
+      "workingDirectory": "."
+    },
+    {
+      "id": "choco",
+      "type": "choco",
+      "enabled": false,
+      "order": 20,
+      "command": "choco push packaging/chocolatey/its-magic.*.nupkg --source %CHOCO_SOURCE%",
+      "tokenEnv": "CHOCO_API_KEY"
+    },
+    {
+      "id": "brew-tap",
+      "type": "brew",
+      "enabled": false,
+      "order": 30,
+      "command": "git push origin HEAD",
+      "tokenEnv": "GITHUB_TOKEN"
+    },
+    {
+      "id": "dockerhub",
+      "type": "docker",
+      "enabled": false,
+      "order": 40,
+      "command": "docker push %DOCKER_IMAGE%",
+      "tokenEnv": "DOCKER_TOKEN"
+    },
+    {
+      "id": "aws-deploy",
+      "type": "cloud",
+      "enabled": false,
+      "order": 50,
+      "command": "aws deploy create-deployment --application-name %APP_NAME% --deployment-group-name %DEPLOY_GROUP% --s3-location bucket=%S3_BUCKET%,bundleType=zip,key=%BUNDLE_KEY%",
+      "credentialEnv": "AWS_PROFILE"
+    },
+    {
+      "id": "custom-release-hook",
+      "type": "custom",
+      "enabled": false,
+      "order": 60,
+      "command": "powershell -ExecutionPolicy Bypass -File scripts/publish-custom.ps1"
+    },
+    {
+      "id": "ssh-server",
+      "type": "ssh",
+      "enabled": false,
+      "order": 70,
+      "hostEnv": "SSH_HOST",
+      "port": 22,
+      "userEnv": "SSH_USER",
+      "authEnv": "SSH_PRIVATE_KEY",
+      "remoteCommand": "cd /opt/its-magic && ./deploy.sh"
+    }
+  ]
+}

package/template/docs/engineering/runbook.md

@@ -139,6 +139,65 @@ Context compaction policy:
 - If unresolved after bounded expansion, answer with explicit "not found in
   current artifacts" rather than broad speculative reads.
 
+## Configurable multi-target publish mode (US-0054 / DEC-0036)
+
+Post-release publish orchestration is configurable and default-safe:
+
+- `RELEASE_PUBLISH_MODE=disabled|confirm|auto` (default `confirm`)
+- `RELEASE_TARGETS_FILE=docs/engineering/release-targets.json`
+- `RELEASE_TARGETS_DEFAULT=` optional comma-separated default target IDs
+
+Target schema contract:
+
+- Canonical target config file: `docs/engineering/release-targets.json`
+- Supported target types:
+  - `npm`, `choco`, `brew`, `git`, `docker`, `cloud`
+  - `custom` (generic command target)
+  - `ssh` (host/user/port/auth reference + remote command)
+- Each target entry must define deterministic fields:
+  - `id` (stable unique target ID)
+  - `type`
+  - `enabled` (`true|false`)
+  - `order` (deterministic execution ordering)
+  - execution details (`command` for non-ssh, `remoteCommand` + host/user/auth refs for `ssh`)
+
+Safety contract:
+
+- Mandatory release gates remain unchanged and must pass before any publish
+  target execution.
+- `confirm` mode requires explicit operator approval before publish execution.
+- Sensitive fields must be env-referenced (`*Env` keys); inline secret literals
+  are not allowed.
+- Invalid target config must fail fast with deterministic diagnostics and no
+  partial side effects.
+
+## Deterministic status reconciliation mode (US-0055 / DEC-0037)
+
+Use the dedicated reconciliation command to normalize status drift across
+canonical and derived artifacts:
+
+- Command: `/status-reconcile`
+- Canonical source: `docs/product/backlog.md` (story `Status`)
+- Derived surfaces: `docs/product/acceptance.md`, `docs/engineering/state.md`,
+  `handoffs/resume_brief.md`
+
+Deterministic behavior:
+
+- Detects mismatches (for example DONE + unchecked ACs, acceptance drift, resume drift).
+- Applies target-scoped reconciliation only to mismatched story blocks/rows.
+- Preserves canonical ownership; derived artifacts reconcile to backlog status.
+- Updates `handoffs/resume_brief.md` to next OPEN story and intended phase.
+- Writes auditable rows to `docs/engineering/status-normalization-report.md`.
+
+Reason-code baseline:
+
+- `STATUS_RECONCILE_APPLIED`
+- `STATUS_RECONCILE_NOOP`
+- `STATUS_RECONCILE_MISSING_INPUT`
+- `STATUS_RECONCILE_CANONICAL_CONFLICT`
+- `STATUS_RECONCILE_PHASE_AMBIGUOUS`
+- `STATUS_RECONCILE_EVIDENCE_MISSING`
+
 ## Optional cross-repo observability mode (US-0034)
 
 Compatibility visibility is optional and default-off in `.cursor/scratchpad.md`:
@@ -463,6 +522,37 @@ and write new isolation evidence before proceeding.
   revert unsafe artifacts if needed, rerun the phase correctly, and ensure
   orchestration-only behavior.
 
+## Strict runtime proof contract (US-0056 / DEC-0038)
+
+Strict runtime proof augments artifact-level isolation evidence. `/auto`,
+`/verify-work`, and `/release` must validate runtime attestation tuples at phase
+boundaries before continuation/finalization.
+
+Required runtime attestation tuple fields:
+
+- `orchestrator_run_id`
+- `runtime_proof_id` (unique per phase run)
+- `phase_id`
+- `role`
+- `proof_issued_at` (ISO UTC / RFC3339)
+- `proof_ttl_seconds`
+- `proof_hash`
+
+Deterministic fail-closed reason codes:
+
+- `RUNTIME_PROOF_MISSING`
+- `RUNTIME_PROOF_INVALID`
+- `RUNTIME_PROOF_REUSED`
+- `RUNTIME_PROOF_STALE`
+- `RUNTIME_PROOF_AMBIGUOUS_LINK`
+
+Boundary behavior:
+
+- Missing/invalid/reused/stale/ambiguous runtime proof blocks progression.
+- Release finalization must consume strict runtime proof in addition to existing
+  isolation evidence checks.
+- Pause/resume provenance must reference latest valid strict-proof boundary.
+
 ## Optional backlog-drain auto mode (US-0044)
 
 `/auto` can optionally continue across multiple planned stories when explicitly
@@ -713,11 +803,40 @@ Use this matrix to validate end-to-end installer/CLI lifecycle behavior:
 |---|---|---|---|
 | Fresh install (`missing`) | `its-magic --mode missing --create` and direct installer | `tests/run-tests.ps1`, `tests/run-tests.sh` | Required files exist + `.its-magic-version` exists |
 | Overwrite + backup | `its-magic --mode overwrite --backup` and direct installer | `tests/run-tests.ps1`, `tests/run-tests.sh` | Backup snapshot contains overwritten framework file |
-| Upgrade lifecycle | `its-magic --mode upgrade` and direct installer | `tests/run-tests.ps1`, `tests/run-tests.sh`, npm local tests | Framework file restored, user-data file preserved |
+| Upgrade lifecycle | `its-magic --mode upgrade` and direct installer | `tests/run-tests.ps1`, `tests/run-tests.sh`, npm local tests | Framework file restored, scratchpad example refreshed, user local scratchpad preserved |
 | Clean-repo safety | `its-magic --clean-repo --yes` and direct installer clean path | `tests/run-tests.ps1`, `tests/run-tests.sh`, CI lifecycle subset | Framework artifacts removed, non-framework marker preserved |
 | Negative path | invalid mode/args | `tests/run-tests.ps1`, `tests/run-tests.sh` | Deterministic non-zero fail-fast behavior |
 | Platform parity subset | npm/brew/choco CI jobs | `.github/workflows/ci.yml` | Lifecycle subset passes on all three runners |
 
+## Scratchpad example upgrade contract (US-0057 / DEC-0039)
+
+`its-magic --mode upgrade` treats `.cursor/scratchpad.local.example.md` as
+framework-owned and `.cursor/scratchpad.local.md` as user-owned.
+
+Expected deterministic outcome:
+- Framework-owned example is refreshed to latest release contract.
+- User local scratchpad remains preserved without overwrite.
+- Installer output reports scratchpad example refresh status
+  (`added|updated|unchanged`) and preservation signal for user local file.
+
+## Deterministic artifact ordering and write discipline (US-0058 / DEC-0040)
+
+Canonical policy source:
+- `docs/engineering/artifact-ordering-policy.md`
+
+Required write discipline:
+- `docs/engineering/state.md`: append-bottom checkpoint writes only.
+- `docs/product/backlog.md`: sorted-canonical story ordering by numeric `US-xxxx`.
+- `docs/product/acceptance.md`: sorted-canonical row ordering aligned to backlog.
+- Handoff surfaces use explicit policy (`prepend-top` or `append-bottom`) per
+  matrix and command contract.
+
+Fail-safe contract:
+- Missing/ambiguous placement anchors fail closed with
+  `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS`.
+- No partial mutation on fail-safe path.
+- Re-run without semantic changes must be ordering-idempotent.
+
 Execution guidance:
 - Local baseline: run `sh tests/run-tests.sh` (or `powershell -ExecutionPolicy Bypass -File tests/run-tests.ps1`).
 - Packaging smoke: run npm local tests in `packaging/npm/`.