feat: bridge Codex v0.4.5–v0.4.7 (bug lifecycle, handoff review gate, resume selection boundary)

- v0.4.5: bug lifecycle consolidation — /bug-report verify with VERIFIED FIXED
  can complete verification, closure, stale triage cleanup, and session-state
  routing under one approved changeset instead of forced verify→close→triage
  handoffs. /bug-triage gains zero-open-bugs closure-refresh path.
- v0.4.6: /handoff mandatory two-round review gate with STANDARD/ADVERSARIAL
  tier selection, pure-document exemptions, finding triage, conditional second
  review, pass caps, audit trail, and no-egress contract (stays inside active
  OpenCode session). AGENTS.md handoff exception expanded for intent-preserving
  fixes and round-two non-trivial-finding stop rule.
- v0.4.7: hard /resume-from-handoff lane-selection boundary — focus arguments
  only bias ranking, single lanes wait for numeric 1, follow-up forks are new
  decisions, FIRST verification cannot be waived. Separated session-cache write
  (Step 6) from briefing (Step 7). AGENTS.md resume exception expanded.
- 3 new audit validators: bug-lifecycle, handoff-review, resume-contract.

Author: Cipher-85

.opencode/VERSION

@@ -1 +1 @@
-0.4.1
+0.4.2

.opencode/audit.sh

@@ -11,6 +11,9 @@
 #   closeout     Check closeout-routing contract on completion skills
 #   checkpoint   Check active.md silent-checkpoint contract on skills/agents
 #   playtest     Check playtest-focus contract on root/continuity/skill surfaces
+#   bug-lifecycle Check bug lifecycle consolidation contract on bug-report/triage
+#   handoff-review Check handoff two-round review-gate contract on handoff/AGENTS.md
+#   resume-contract Check resume lane-selection boundary on resume-from-handoff
 #   runtime      Check for stale references
 #   config       Validate opencode.json
 #   hooks        Test hook scripts
@@ -27,7 +30,7 @@ command="${1:-all}"
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --root) root="$(cd "$2" && pwd -P)"; shift 2 ;;
-    all|agents|skills|runtime|config|hooks|smoke|release|closeout|checkpoint|playtest) command="$1"; shift ;;
+    all|agents|skills|runtime|config|hooks|smoke|release|closeout|checkpoint|playtest|bug-lifecycle|handoff-review|resume-contract) command="$1"; shift ;;
     *) shift ;;
   esac
 done
@@ -257,6 +260,208 @@ run_playtest_focus() {
   printf '  %d playtest-focus surfaces checked\n' "$checked"
 }
 
+run_bug_lifecycle() {
+  printf '\n── Bug Lifecycle Contract ────────────────────────────────\n'
+  local checked=0
+
+  # --- bug-report required phrases ---
+  local report="$root/.opencode/skills/bug-report/SKILL.md"
+  checked=$((checked + 1))
+  if [ ! -f "$report" ]; then fail "bug-report/SKILL.md (missing)"; else
+    local report_norm; report_norm=$(tr -s '[:space:]' ' ' < "$report")
+    local -a req=(
+      "treat verification, closure, stale triage"
+      "one deterministic bug lifecycle operation"
+      "Do not stop after VERIFIED FIXED to offer"
+      "refresh stale triage metadata under the same approval"
+      "zero-open-bugs refresh"
+      "derived checkpoint"
+      'Do not ask a separate "May I write?" for'
+      "Do not bundle and stop for user decision if triage would require assigning"
+    )
+    local missing=() p
+    for p in "${req[@]}"; do
+      grep -qiF "$p" <<< "$report_norm" 2>/dev/null || missing+=("$p")
+    done
+    # Forbidden old-language fragments
+    local -a forbidden=(
+      "is referenced in the triage report"
+      "write the closure record and update status"
+      "remove it from the active list"
+    )
+    local bad=()
+    for p in "${forbidden[@]}"; do
+      grep -qiF "$p" <<< "$report_norm" 2>/dev/null && bad+=("$p")
+    done
+    if [ "${#missing[@]}" -eq 0 ] && [ "${#bad[@]}" -eq 0 ]; then
+      pass "bug-report/SKILL.md (lifecycle contract)"
+    else
+      local d=""
+      [ "${#missing[@]}" -gt 0 ] && d+=" missing: ${missing[*]}"
+      [ "${#bad[@]}" -gt 0 ] && d+=" forbidden-present: ${bad[*]}"
+      fail "bug-report/SKILL.md (lifecycle contract)$d"
+    fi
+  fi
+
+  # --- bug-triage required phrases ---
+  local triage="$root/.opencode/skills/bug-triage/SKILL.md"
+  checked=$((checked + 1))
+  if [ ! -f "$triage" ]; then fail "bug-triage/SKILL.md (missing)"; else
+    local triage_norm; triage_norm=$(tr -s '[:space:]' ' ' < "$triage")
+    local -a req2=(
+      "zero-open-bugs closure refresh"
+      "Treat it as metadata cleanup"
+      "non-blocking follow-up"
+      "Exception for bundled bug lifecycle cleanup"
+      "deterministic metadata cleanup"
+      "It must be explicitly marked non-blocking if it cannot be completed safely"
+      "Do not bundle if the triage work would require assigning priorities"
+    )
+    local missing2=() p2
+    for p2 in "${req2[@]}"; do
+      grep -qiF "$p2" <<< "$triage_norm" 2>/dev/null || missing2+=("$p2")
+    done
+    if [ "${#missing2[@]}" -eq 0 ]; then
+      pass "bug-triage/SKILL.md (lifecycle contract)"
+    else
+      fail "bug-triage/SKILL.md missing: ${missing2[*]}"
+    fi
+  fi
+  printf '  %d bug-lifecycle surfaces checked\n' "$checked"
+}
+
+run_handoff_review() {
+  printf '\n── Handoff Review Gate Contract ──────────────────────────\n'
+  local checked=0
+
+  # --- handoff SKILL.md required phrases ---
+  local skill="$root/.opencode/skills/handoff/SKILL.md"
+  checked=$((checked + 1))
+  if [ ! -f "$skill" ]; then fail "handoff/SKILL.md (missing)"; else
+    local skill_norm; skill_norm=$(tr -s '[:space:]' ' ' < "$skill")
+    local -a req=(
+      "## Round 1"
+      "## Round 2"
+      "\`STANDARD\`"
+      "\`ADVERSARIAL\`"
+      "Foundation ADR cluster closure"
+      "pure design/process-document"
+      "self-review is sufficient and the native cross-check is skipped"
+      "Mixed code-and-document changes are not exempt"
+      "distinct native review pass"
+      "current OpenCode session"
+      "\`HIGH\`, \`MEDIUM\`, or \`LOW\`"
+      "\`CLEAN\`"
+      "\`path:line\`"
+      "If uncertain whether the work meets a major trigger, use \`STANDARD\`"
+      "quoted verbatim"
+      "stop before Phase 1"
+      "second native cross-check"
+      "\`HIGH\` finding"
+      "cross-cutting executable behavior"
+      "Trivial and confidently intent-preserving only"
+      "Any non-trivial fix"
+      "Do not run a third pass"
+      "three native review passes"
+      "fourth native review pass"
+      "active reported context percentage"
+      "review audit trail"
+      "every finding"
+      "Only then proceed to Phase 1"
+    )
+    local missing=() p
+    for p in "${req[@]}"; do
+      grep -qF "$p" <<< "$skill_norm" 2>/dev/null || missing+=("$p")
+    done
+    if [ "${#missing[@]}" -eq 0 ]; then
+      pass "handoff/SKILL.md (review gate contract)"
+    else
+      fail "handoff/SKILL.md missing: ${missing[*]}"
+    fi
+  fi
+
+  # --- AGENTS.md required phrases ---
+  local agents="$root/AGENTS.md"
+  checked=$((checked + 1))
+  if [ ! -f "$agents" ]; then fail "AGENTS.md (missing)"; else
+    local agents_norm; agents_norm=$(tr -s '[:space:]' ' ' < "$agents")
+    local -a req2=(
+      "files already created or materially modified during the session"
+      "intent-preserving review fixes"
+      "active OpenCode session"
+      "Round-two non-trivial findings"
+      "external data-egress approval"
+      "new intent, architecture, game-feel, balance, or scope decisions"
+    )
+    local missing2=() p2
+    for p2 in "${req2[@]}"; do
+      grep -qF "$p2" <<< "$agents_norm" 2>/dev/null || missing2+=("$p2")
+    done
+    if [ "${#missing2[@]}" -eq 0 ]; then
+      pass "AGENTS.md (handoff review exception)"
+    else
+      fail "AGENTS.md missing: ${missing2[*]}"
+    fi
+  fi
+  printf '  %d handoff-review surfaces checked\n' "$checked"
+}
+
+run_resume_contract() {
+  printf '\n── Resume Lane-Selection Contract ────────────────────────\n'
+  if python3 - "$root" <<'PY'
+import re, sys, os
+root = sys.argv[1]
+rel = ".opencode/skills/resume-from-handoff/SKILL.md"
+path = os.path.join(root, rel)
+if not os.path.isfile(path):
+    print(f"  ! {rel}: missing file")
+    sys.exit(1)
+text = open(path, encoding="utf-8").read()
+norm = re.sub(r"\s+", " ", text)
+
+required = (
+    "A focus argument biases ranking; it does not select a lane.",
+    "Never start an unselected lane.",
+    "recommendation as the first option",
+    "wait for the user to reply `1`",
+    "Resume selection authorizes entering only the selected workflow",
+    "FIRST verification cannot be waived by choosing another lane",
+    "Follow-up fork",
+    "`question` tool",
+    "Playable/Slice State Source",
+    "production/stage.txt",
+    ".opencode/docs/workflow-catalog.yaml",
+    "production/session-state/active.md",
+)
+missing = [p for p in required if p not in norm]
+if missing:
+    print(f"  ! {rel}: missing phrase(s): " + ", ".join(missing))
+
+fails = len(missing)
+for i, line in enumerate(text.splitlines(), start=1):
+    lower = line.lower()
+    starts_lane = re.search(r"\b(?:start|begin|enter)\b", lower)
+    bypasses = any(w in lower for w in (
+        "automatically", "immediately", "without waiting", "without selection"
+    ))
+    forbidden = any(w in lower for w in (
+        "do not", "don't", "never", "must not", "cannot"
+    ))
+    if starts_lane and bypasses and not forbidden:
+        print(f"  ! {rel}:{i}: automatic lane startup forbidden; "
+              "pause for selection boundary")
+        fails += 1
+
+print(f"  resume-from-handoff checked, {fails} violation(s)")
+sys.exit(1 if fails else 0)
+PY
+  then
+    pass "resume selection contract satisfied"
+  else
+    fail "resume selection contract violations"
+  fi
+}
+
 run_runtime() {
   printf '\n── Runtime References ──────────────────────────────────────\n'
   # Check for stale Claude references
@@ -404,6 +609,9 @@ case "$command" in
     run_closeout
     run_checkpoint
     run_playtest_focus
+    run_bug_lifecycle
+    run_handoff_review
+    run_resume_contract
     run_runtime
     run_config
     run_hooks
@@ -414,12 +622,15 @@ case "$command" in
   closeout) run_closeout ;;
   checkpoint) run_checkpoint ;;
   playtest) run_playtest_focus ;;
+  bug-lifecycle) run_bug_lifecycle ;;
+  handoff-review) run_handoff_review ;;
+  resume-contract) run_resume_contract ;;
   runtime)  run_runtime ;;
   config)   run_config ;;
   hooks)    run_hooks ;;
   smoke)    run_smoke ;;
   release)  run_release ;;
-    *) printf 'Unknown command: %s\nAvailable: all, agents, skills, closeout, checkpoint, playtest, runtime, config, hooks, smoke, release\n' "$command" >&2; exit 2 ;;
+    *) printf 'Unknown command: %s\nAvailable: all, agents, skills, closeout, checkpoint, playtest, bug-lifecycle, handoff-review, resume-contract, runtime, config, hooks, smoke, release\n' "$command" >&2; exit 2 ;;
 esac
 
 printf '\n── Result: %d error(s) ──\n' "$errors"

.opencode/skills/bug-report/SKILL.md

@@ -105,7 +105,47 @@ Produce a verification verdict:
 - **STILL PRESENT** — bug reproduces as described; fix did not resolve the issue
 - **CANNOT VERIFY** — automated checks inconclusive; manual playtest required
 
-Ask: "May I update `production/qa/bugs/[BUG-ID].md` to set Status: Verified Fixed / Still Present / Cannot Verify?"
+If the verdict is **VERIFIED FIXED**, treat verification, closure, stale triage
+metadata cleanup, and session-state routing as one deterministic bug lifecycle
+operation when the facts are unambiguous.
+
+Before writing, present the verification evidence and ask once for the full
+changeset:
+
+> "May I update these files to mark [BUG-ID] Verified Fixed, add verification
+> evidence, close the bug, refresh stale triage metadata when safe, and update
+> the derived checkpoint in `production/session-state/active.md`?
+> Files: `production/qa/bugs/[BUG-ID].md`, [any affected
+> `production/qa/bug-triage-*.md` files], `production/session-state/active.md`."
+
+Do not stop after VERIFIED FIXED to offer `/bug-report close [BUG-ID]` as the
+next action when closure facts are deterministic. Do not ask a separate "May I
+write?" for `production/session-state/active.md` when the update is only a
+derived checkpoint for completed bug lifecycle work. Do not ask a separate "May
+I write?" for this file.
+
+Bundle only deterministic metadata cleanup:
+- Set top-level `**Status**: Verified Fixed`.
+- Add or update verification evidence with the command(s), grep checks, commit
+  or file evidence, and verifier.
+- Append the Closure Record from Phase 2D and set top-level `**Status**: Closed`
+  when the closure record can be completed from known facts.
+- Refresh affected `production/qa/bug-triage-*.md` reports only when the refresh
+  removes closed bugs, updates open/closed counts, clears a stale recommended
+  action, or records "0 open bugs" without assigning priorities or changing
+  sprint scope.
+- Update `production/session-state/active.md` only with derived checkpoint
+  routing: completed bug lifecycle work, files touched, owed verification, and
+  the next valid Session Worklist lane.
+
+Do not bundle and stop for user decision if triage would require assigning
+priorities, choosing sprint scope, marking bugs Won't Fix, changing severity, or
+resolving conflicting bug states.
+
+If the verdict is **STILL PRESENT** or **CANNOT VERIFY**, ask:
+
+> "May I update `production/qa/bugs/[BUG-ID].md` to set Status: Still Present /
+> Cannot Verify and add the verification evidence?"
 
 If STILL PRESENT: reopen the bug, set Status back to Open, and suggest re-running `/hotfix [BUG-ID]`.
 
@@ -130,9 +170,29 @@ Append a closure record to the bug file:
 
 Update the top-level `**Status**: Open` field to `**Status**: Closed`.
 
-Ask: "May I update `production/qa/bugs/[BUG-ID].md` to mark it Closed?"
+If the bug is already `Verified Fixed`, close the bug and refresh stale triage
+metadata under the same approval when the refresh is safe deterministic cleanup.
+Before writing, list the exact files and ask once:
 
-After closing, check `production/qa/bug-triage-*.md` — if the bug appears in an open triage report, note: "Bug [ID] is referenced in the triage report. Run `/bug-triage` to refresh the open bug count."
+> "May I update these files to close [BUG-ID], refresh stale triage metadata
+> when safe, and update the derived checkpoint in
+> `production/session-state/active.md`?
+> Files: `production/qa/bugs/[BUG-ID].md`, [any affected
+> `production/qa/bug-triage-*.md` files], `production/session-state/active.md`."
+
+Do not ask a separate "May I write?" for `production/session-state/active.md`
+when the update is only a derived checkpoint for completed bug lifecycle work.
+Do not ask a separate "May I write?" for this file.
+
+Safe stale triage metadata refresh includes removing the closed bug from open
+bug tables, updating open/closed counts, clearing stale "fix this bug" actions,
+and recording a zero-open-bugs refresh. It must not assign priorities, choose
+sprint scope, mark bugs Won't Fix, change severity, or resolve conflicting bug
+states.
+
+If stale triage metadata exists but is unsafe to refresh automatically, close
+the bug and mark triage cleanup as non-blocking owed follow-up instead of
+blocking closure.
 
 ---
 
@@ -161,5 +221,8 @@ After saving, suggest based on mode:
 - Never mark a bug closed without verification — a fix that doesn't verify is still Open
 
 **After verify returns VERIFIED FIXED:**
-- Run `/bug-report close [BUG-ID]` — write the closure record and update status
-- Run `/bug-triage` to refresh the open bug count and remove it from the active list
+- When closure facts are deterministic, complete verification, closure, stale
+  triage metadata cleanup, and derived session-state routing under the same
+  approved changeset.
+- If closure or triage refresh requires a manual decision, stop at the decision
+  point and make the blocked item explicit.

.opencode/skills/bug-triage/SKILL.md

@@ -21,6 +21,9 @@ ensures no critical bug is lost between sprints.
 - Sprint start — assign open bugs to the new sprint or backlog
 - After `/team-qa` completes and new bugs have been filed
 - When the bug count crosses 10+ open items
+- As bundled metadata cleanup after `/bug-report verify [BUG-ID]` or
+  `/bug-report close [BUG-ID]` closes a bug and stale triage report fields can
+  be refreshed without new prioritization decisions
 
 ---
 
@@ -51,6 +54,13 @@ If no bug files found:
 
 Stop and report. Do not proceed if no bugs exist.
 
+If this run is a zero-open-bugs closure refresh started from an approved
+`/bug-report verify [BUG-ID]` or `/bug-report close [BUG-ID]` lifecycle, do not
+stop for a separate triage decision. Treat it as metadata cleanup: update the
+affected stale triage report so the open bug count, priority tables, and
+recommended action reflect that no bugs remain open. Mark any broader trend or
+sprint-priority work as non-blocking follow-up.
+
 ### Step 2b — Load sprint context
 
 Read the most recently modified file in `production/sprints/` to understand:
@@ -222,6 +232,19 @@ Present the report in conversation, then ask:
 
 Write only after approval.
 
+Exception for bundled bug lifecycle cleanup: when `/bug-report verify [BUG-ID]`
+or `/bug-report close [BUG-ID]` already obtained approval for the full
+changeset, do not ask a second triage write prompt for deterministic metadata
+cleanup. The approval must have listed the exact stale
+`production/qa/bug-triage-*.md` file(s) being updated.
+
+Bundled triage cleanup is allowed only when it removes closed bugs from open
+tables, updates counts, clears stale recommended actions, or records a
+zero-open-bugs closure refresh. It must be explicitly marked non-blocking if it
+cannot be completed safely. Do not bundle if the triage work would require
+assigning priorities, choosing sprint scope, marking bugs Won't Fix, changing
+severity, or resolving conflicting bug states.
+
 After writing:
 - If any S1 bugs are unassigned: "S1 bugs must be assigned before the sprint
   can be considered healthy. Run `/sprint-status` to see current capacity."