[refactor] Audit plugin-update Phase 1.5 / Phase 2.5 AskUserQuestion default options for consistency with #60 Phase 0.5 abort-default safety policy

[kiki830621]

Problem

Source: surfaced during /idd-implement #60 reproduction (Step 5.7)

#60 introduces Phase 0.5 to plugin-tools:plugin-update with an explicit default-option safety policy: abort is default for any state with multiple sensible actions; push as-is only for unambiguous clean+unpushed.

The skill already has AskUserQuestion calls in two other phases that predate #60:

• Phase 1.5 (L161) — check_external_deps: detects MCP/CLI binary out-of-sync with shell version, asks user 「順便更新 / 只更新 shell / 中止」
• Phase 2.5 (L437) — check_readme_freshness: detects README drift from current version, asks user 「auto-update / skip update / abort」

Both these AskUserQuestion blocks may have default options that don't follow the same safety-first policy Phase 0.5 commits to. Inconsistent default policy across the same skill = surprising UX (users build expectation from Phase 0.5 abort-default, then Phase 1.5/2.5 default to action without their explicit consent).

Type

refactor (consistency audit)

Expected behavior

Audit each AskUserQuestion in plugin-update and apply the same Phase 0.5 default-option policy:

Rule: abort (or "skip update without changes") is the default for any state with multiple sensible actions. Active changes (push, auto-update binary, regenerate README) are only the default in unambiguous happy-path cases where doing nothing would be more frustrating than doing something.

For each phase:

1. Phase 1.5 (binary deps): when binary version drifts from shell, what's the right default? auto-update binary is opinionated (skill installs new binary on user's behalf); skip (just print warning, let user decide separately) is safer. Audit and align.
2. Phase 2.5 (README freshness): when README is stale, default auto-regen vs skip — skip is safer (skill won't surprise-rewrite docs); auto-regen is convenient but assumes user wants regeneration. Audit and align.

Actual behavior

Not yet audited. Pre-#60 the skill's AskUserQuestion default options were chosen ad-hoc; #60 introduces the first explicit cross-phase policy. Without consistency audit, the same skill has 3 different defaulting philosophies.

Priority

P3 — schedule. After #60 lands, audit existing 2 phases (≈10 min reading + AskUserQuestion redrafting). Not blocking but worth doing while the design rationale is fresh.

Strategy sketch

1. Read plugin-update SKILL.md L161 + L437 — extract current AskUserQuestion options + identify which is marked default
2. For each, evaluate: does the current default match Phase 0.5 policy (abort-for-ambiguous, action-for-happy-path)?
3. If not, propose adjustment; commit as small refactor (not standalone Plan tier — Simple).

Source

surfaced during /idd-implement #60 reproduction (Step 5.7) — observed when referencing existing AskUserQuestion patterns as precedent for Phase 0.5 design.

Related

• plugin-update: add Step 0 git-state preview + commit/push confirmation dialog before mutating origin #60 (parent — established the default-option policy this audit applies)
• L161 / L437 in plugins/plugin-tools/skills/plugin-update/SKILL.md

[kiki830621]

Implementation Plan (cluster-PR mode)

This issue is part of a 4-issue refactor cluster sharing 1 feature branch + 1 PR. Plan covers all 4 issues for transparency; commits use Refs #N to match each item to its source issue.

Cluster scope:

• [refactor] archive-mail Step 2.1 read-only invariant has no structural enforcement (sister concern from #49) #56 — archive-mail.md Step 2.1 read-only invariant marker (Option A per issue body)
• [bug] archive-mail Step 2.1 find/while loop not null-safe to newlines in filenames (sister concern from #49) #57 — archive-mail.md Step 2.1 null-safe find -print0 + read -d '' pattern
• [refactor] Audit plugin-update Phase 1.5 / Phase 2.5 AskUserQuestion default options for consistency with #60 Phase 0.5 abort-default safety policy #68 — plugin-update Phase 1.5 + 2.5 AskUserQuestion default-option policy audit (documentation clarification)
• [refactor] plugin-update Phase 0.5 Step 5 use mktemp instead of /tmp/touched-plugins.txt (sibling concern from #60) #70 — plugin-update Phase 0.5 Step 5 use mktemp instead of /tmp/touched-plugins.txt

Branch: idd/cluster-refactor-archive-plugin-update

Files & Changes (per-issue)

#56 (commit 1)

• plugins/che-apple-mail-mcp/commands/archive-mail.md Step 2.1 — add invariant marker comment at top of the bash block:

  # === INVARIANT: this block is READ-ONLY w.r.t. $symlink_dir ===
  # Allowed: find / head / awk / cat / grep
  # FORBIDDEN: mv / rm / cp / > / >> / tee / chmod (against $symlink_dir or its target)
  # If you need to write, do it OUTSIDE this block.
  

  Pure self-documenting (Option A per issue body, lowest cost). Future maintainer reading the block sees the invariant before editing.

#57 (commit 2)

• plugins/che-apple-mail-mcp/commands/archive-mail.md Step 2.1 — apply null-safe pattern to both find invocations (outer + inner):
  • Outer: find -P "${output_dir}" -maxdepth 1 -type l -print0 + while IFS= read -r -d '' symlink_dir
  • Inner: find -P "$symlink_dir/" -maxdepth 2 -name "*.md" -type f -print0 + while IFS= read -r -d '' mdfile

#68 (commit 3)

• plugins/plugin-tools/skills/plugin-update/SKILL.md Phase 1.5 + Phase 2.5 — documentation clarification, NOT behavior change:
  • Audit found Phase 1.5 ("順便更新" first) + Phase 2.5 ("更新 README" first) use action-default, NOT abort-default
  • But this is deliberately aligned with Phase 0.5 rule's exception clause: "Active default in unambiguous happy-path cases where doing nothing would be more frustrating than doing something"
  • Add clarifying paragraph after Phase 1.5 + 2.5 AskUserQuestion blocks explaining the rule application
  • No option reordering (existing UX kept)

#70 (commit 4)

• plugins/plugin-tools/skills/plugin-update/SKILL.md Phase 0.5 Step 5 — replace hardcoded /tmp/touched-plugins.txt with mktemp + cleanup trap:

  TMPFILE=$(mktemp -t plugin-update-touched.XXXXXX)
  trap "rm -f '$TMPFILE'" EXIT
  ...write to $TMPFILE...

  Defensive hygiene — single-user macOS realistic threat is low, but mktemp random suffix avoids race condition on shared /tmp mounts.

Sequencing

4 disjoint changes across 2 files (archive-mail.md for #56+#57, SKILL.md for #68+#70). 4 separate commits, any order. Choose: #56 → #57 → #68 → #70 (matches issue number order).

Decision Points (locked in)

• D1 — [refactor] archive-mail Step 2.1 read-only invariant has no structural enforcement (sister concern from #49) #56 Option A only: invariant marker comment, NOT structural enforcement (Option B/C deferred).
• D2 — [refactor] Audit plugin-update Phase 1.5 / Phase 2.5 AskUserQuestion default options for consistency with #60 Phase 0.5 abort-default safety policy #68 audit conclusion: Phase 1.5 + 2.5 action-defaults are JUSTIFIED by Phase 0.5 rule's exception clause for "unambiguous happy-path / reversible action / frequent dev flow". No behavior change; document the alignment.
• D3 — [refactor] plugin-update Phase 0.5 Step 5 use mktemp instead of /tmp/touched-plugins.txt (sibling concern from #60) #70 mktemp pattern: standard mktemp -t + trap rm EXIT (per issue body's recommended snippet). No inline-variable alternative (would lose the trap cleanup safety).

Risks & Mitigations

• Trailing whitespace risk (per plugin-update: add Step 0 git-state preview + commit/push confirmation dialog before mutating origin #60 verify finding): keep edits surgical, run git diff --check before commit.
• [bug] archive-mail Step 2.1 find/while loop not null-safe to newlines in filenames (sister concern from #49) #57 outer + inner find both touched: ensure both finds get -print0 consistently — read -r on a partially-converted pipeline would mis-parse.
• [refactor] Audit plugin-update Phase 1.5 / Phase 2.5 AskUserQuestion default options for consistency with #60 Phase 0.5 abort-default safety policy #68 wording: audit clarification must NOT contradict existing line 358-360 + 681 tables that explicitly state "ASK + AUTO-SYNC" rationale. Build on those, don't replace.
• [refactor] plugin-update Phase 0.5 Step 5 use mktemp instead of /tmp/touched-plugins.txt (sibling concern from #60) #70 trap collision: if Phase 0.5 Step 5 already has a trap (it doesn't currently), need to chain. Verify before edit.

Out-of-scope

• [refactor] archive-mail Step 2.1 read-only invariant has no structural enforcement (sister concern from #49) #56 Option B (bash trap-based) / Option C (pre-commit hook scanning) — defer
• [refactor] Audit plugin-update Phase 1.5 / Phase 2.5 AskUserQuestion default options for consistency with #60 Phase 0.5 abort-default safety policy #68 Phase 1.5 / 2.5 behavior change (option reordering) — keep deliberate action-default per existing rationale
• [refactor] plugin-update Phase 0.5 Step 5 use mktemp instead of /tmp/touched-plugins.txt (sibling concern from #60) #70 inline-variable alternative — mktemp + trap chosen for safety

[kiki830621]

Implementation Complete

Checklist

• Add Phase 1.5 default-option policy alignment note (Phase 0.5 exception clause) → commit f25621e
• Add Phase 2.5 default-option policy alignment note (reversible draft framing) → commit f25621e

Legend: - [x] done · - [~] skipped · - [-] won't fix
idd-close will refuse to close if any - [ ] remains.

Changes

• f25621e docs(plugin-update): clarify Phase 1.5/2.5 default-option policy alignment with Phase 0.5 (Refs #68)

Files Changed

• plugins/plugin-tools/skills/plugin-update/SKILL.md — +14 lines, 2 inserted blockquote sections (one after Phase 1.5 default-option table, one after Phase 2.5 default-option table)

Cluster PR

PR #72 (cluster of #56 #57 #68 #70). Verify pending — run /idd-verify --pr 72.

Audit conclusion (no behavior change)

Phase 1.5 (順便更新 action default) and Phase 2.5 (更新 README action default) appeared to diverge from Phase 0.5's abort-default safety policy. Audit found they correctly apply Phase 0.5 rule's exception clause: "active default reserved for unambiguous happy-path / reversible action / frequent dev flow."

• Phase 1.5: binary-out-of-sync in dev flow IS unambiguous happy path; binary install reversible (mcp-deploy / cli-upgrade re-runnable). Frequent. → action default justified.
• Phase 2.5: '更新 README' option proposes diff (read CHANGELOG + git log → draft → user review → commit). User-confirmation gate intact. Reversible draft. → action default justified.
• Phase 0.5 contrast: release-time push to public marketplace is irreversible (force-push to public is bad day) → abort default warranted regardless of user-in-session.

Each phase's default reflects its action's risk profile.

Scope Compliance

Pure documentation. No behavioral change. Same default-option choices as before this PR — only the rationale is now explicit in the doc, preventing future audits from re-flagging the apparent divergence.

Sister Bugs Filed

None. Audit covered Phase 1.5 / 2.5 / 0.5 default-option policies comprehensively; no other phases use AskUserQuestion with default selection.

Next: verification pending

[kiki830621]

Verify (via PR #72 cluster)

Result: PASS (after 4c1b102 verify-fix) — 0 blocking remaining.
Full report: #72 (comment)

This issue's findings: see "#68" section in the linked report.

Engine: lighter cluster ensemble (combined Claude reviewer + Codex GPT-5.5 xhigh) — pure-docs/refactor cluster.

Next: pending human review + squash merge of PR #72, then /idd-close #56 #57 #68 #70.