[refactor] archive-mail Step 2.1 read-only invariant has no structural enforcement (sister concern from #49)

[kiki830621]

Problem

From verification of #49:
「Read-only invariant for sibling-archive scan has no structural enforcement (just code comment). Future maintainer adding mv/rm to Step 2.1 won't be caught by any guard.」
— Source: idd-verify #49 (DA new finding, INFO level)

archive-mail.md Step 2.1 (added in #49) claims:

"Read-only:never mv / rm / > against symlink target;find + head + awk only。"

But this is enforced only by:

1. The current bash pseudocode happens to use only read operations
2. A code comment saying "read-only"

Future maintainer editing Step 2.1 to "extend the dedup with metadata sync" or "rebuild the symlinked archive index" could add mv / >> operations, breaking the invariant silently — no test, no lint, no scan-time check.

Type

refactor (defensive guardrail)

Why this matters

archive-mail.md is a skill markdown. AI executor reads the bash blocks as instructions. If a future commit adds destructive ops to Step 2.1, AI will execute them. The read-only claim becomes a lie. Symlinked archives (which point to applications archives, project completions, sealed historical records) get unintended writes.

Priority

LOW / INFO — no current break, but invariant decay risk.

Strategy sketch

Three mitigation options:

Option A: explicit invariant marker comment

Add at top of Step 2.1 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.

Self-documenting; relies on future maintainer reading.

Option B: bash trap-based check (in real shell impl)

If archive-mail.md ever gets a real bash implementation file:

# Set readonly flag for entire scan, fail-fast on any write attempt
set -o noclobber  # or other guards

But this is hard for skill-as-AI-instructions paradigm.

Option C: pre-commit hook scanning Step 2.1 region for forbidden tokens

Pre-commit hook checks git diff plugins/.../archive-mail.md for mv|rm|cp|>|tee within the Step 2.1 block boundaries. Heavy but most reliable.

Recommendation

Option A (comment marker) — cheapest, future-proof for AI executors that read instructions literally.

Related

• archive-mail: support workspaces with nested communications layout and symlinked historical archives #49 (parent — introduced Step 2.1)

[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 invariant marker comment to archive-mail Step 2.1 sibling-archive dedup block → commit 3b01d3f

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

Changes

• 3b01d3f refactor(archive-mail): add read-only invariant marker comment to Step 2.1 (Refs #56)

Files Changed

• plugins/che-apple-mail-mcp/commands/archive-mail.md — +6 lines comment block above Step 2.1 bash code

Cluster PR

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

Scope Compliance

Pure documentation comment, no behavioral change. The invariant being documented (Step 2.1 is read-only w.r.t. $symlink_dir) was already true before this commit — comment makes the contract explicit for future maintainers.

Sister Bugs Filed

None. Mid-implementation reproduction window surfaced no further sister concerns beyond the original cluster (#56 #57 #68 #70 all addressed in this PR).

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 "#56" 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.