[docs] README workspace pattern '100% backward compat' wording too strong (sister concern from #49)

[kiki830621]

Problem

From verification of #49:
「README L99 backward compat promise wording loose for zero-config + multi-dir-coexist case (where neither communications/email nor correspondence/emails are pinned, both exist with content).」
— Source: idd-verify #49 (DA new finding)

plugins/che-apple-mail-mcp/README.md Workspace Patterns section (added in #49) promises:

"Detection 不會 fire,既有行為 100% backward compat。"

But the 100% wording is too strong for one edge case: zero-config user with both communications/email/ and correspondence/emails/ populated (mid-migration scenario without explicit pin).

Type

docs

Why this matters

Detection's ambiguity guard (currently broken — see #5 sister issue) is supposed to abort on this case. But:

1. The guard is incomplete (docs(macdoc skill): 新增批次 OCR + Ollama 並行章節 #5 covers root fix)
2. Even fixed, the abort behavior IS a backward-compat change (pre-v2.17 silently used default; v2.17+ aborts with explicit-pin recommendation)

Calling this "100% backward compat" is technically incorrect. README should:

1. Either qualify: "Backward compat preserved for explicitly-configured workspaces; mid-migration zero-config workspaces with both layouts will be flagged for explicit pin"
2. Or remove the "100%" word

Priority

P3 — nit. Rare case but the doc is currently misleading.

Strategy sketch

- 詳見下方 [Workspace Patterns](#workspace-patterns-v2170)。Detection 不會 fire,既有行為 100% backward compat。
+ 詳見下方 [Workspace Patterns](#workspace-patterns-v2170)。已 explicit-pin 的 workspace 行為不變;zero-config 且有 multiple legacy layout 的 mid-migration workspace 會被 ambiguity guard flag,要求 explicit pin。

Related

• docs(macdoc skill): 新增批次 OCR + Ollama 並行章節 #5 (covered by ambiguity guard root fix)
• archive-mail: support workspaces with nested communications layout and symlinked historical archives #49 (parent)

Current Status

Phase: implemented (cluster-PR mode)
Last updated: 2026-05-10 by /idd-implement cluster

Key Decisions

• Part of 4-issue docs cluster ([docs] Backfill CHANGELOG [2.16.1] entry (sister concern from #49) #52 + [docs] archive-mail YAML message_id parser brittle — reduce 'schema diversity' claim or strengthen (sister concern from #49) #54 + [docs] README workspace pattern '100% backward compat' wording too strong (sister concern from #49) #55 + [docs] plugin-tools CHANGELOG [1.15.0] entry has placeholder date — backfill (tangential from #60) #64) sharing PR cluster: 4 docs follow-ups from #49 / #60 IDD lifecycles #71 + cluster branch idd/cluster-docs-followups-49-60.
• Implementation: README 100% backward-compat wording softened.
• Commit: a89bca3 references this issue via Refs PsychQuant/psychquant-claude-plugins#55.
• Pure docs change — no code logic, no test impact, no version bump.

Scope Changes

• Single file change per issue, all 4 issues touch different files (no inter-issue scope overlap).
• No sister bugs surfaced (Step 5.7 sweep returned empty).

Blocking

• (none) Awaiting /idd-verify --pr 71 cluster verify + per-issue /idd-close after merge.

Commits

• a89bca3: README 100% backward-compat wording softened (Refs [docs] README workspace pattern '100% backward compat' wording too strong (sister concern from #49) #55)
• (cluster total: 4 commits — see PR cluster: 4 docs follow-ups from #49 / #60 IDD lifecycles #71 for full diff)

Current Status

Phase: verified
Last updated: 2026-05-10 by /idd-verify cluster

Key Decisions

• Cluster verify (PR cluster: 4 docs follow-ups from #49 / #60 IDD lifecycles #71) returned PASS after empirical adjudication of Codex GPT-5.5 cross-model dissent. Full report: cluster: 4 docs follow-ups from #49 / #60 IDD lifecycles #71 (comment)
• This issue's verify-stage fix(es): (none — verify PASS first round)
• Codex caught parser-behavior accuracy issue Claude reviewer flat-passed — cross-model verify did its job.
• 2 Codex HIGH findings on ### Notes non-KAC section names rejected as false positives — empirical evidence shows ### Notes is established repo convention (6× usage in che-apple-mail-mcp CHANGELOG, also batch-ocr/plugin-tools/parallel-ai-agents).
• DA skipped — disagreements were empirically resolvable via repo grep + bash awk test, no need for separate DA agent.

Scope Changes

• (none from this issue's perspective; cluster-level only)
• Cross-issue observation filed inline in master report: plugin currently v2.18.1 but CHANGELOG missing [2.18.1] entry (same KAC drift class as [docs] Backfill CHANGELOG [2.16.1] entry (sister concern from #49) #52) — suggested follow-up for next cluster.

Blocking

• (none) Awaiting PR cluster: 4 docs follow-ups from #49 / #60 IDD lifecycles #71 merge + per-issue /idd-close closing summary.

Commits

• c04f66d: fix(docs-cluster): apply /idd-verify PR cluster: 4 docs follow-ups from #49 / #60 IDD lifecycles #71 codex findings (Refs [docs] Backfill CHANGELOG [2.16.1] entry (sister concern from #49) #52 [docs] archive-mail YAML message_id parser brittle — reduce 'schema diversity' claim or strengthen (sister concern from #49) #54 [docs] plugin-tools CHANGELOG [1.15.0] entry has placeholder date — backfill (tangential from #60) #64)
• (this-issue commit on cluster branch): see PR cluster: 4 docs follow-ups from #49 / #60 IDD lifecycles #71 for full diff

Current Status

Phase: closed
Last updated: 2026-05-10 by /idd-close cluster

Key Decisions

• Closed via cluster /idd-close PsychQuant/psychquant-claude-plugins#52 PsychQuant/psychquant-claude-plugins#54 PsychQuant/psychquant-claude-plugins#55 PsychQuant/psychquant-claude-plugins#64 after PR cluster: 4 docs follow-ups from #49 / #60 IDD lifecycles #71 merged.
• Per-issue closing summary written independently (NOT batched — IDD discipline).
• Step 0 supersession active(Implementation Complete > Checklist all - [x])→ Strategy/Plan unchecked items 視為 superseded per #515 fix。
• Step 1.5 PR Gate PASS(PR cluster: 4 docs follow-ups from #49 / #60 IDD lifecycles #71 MERGED at 2026-05-10T12:02:27Z as 1557fbf)。
• Step 1.6 semantic gate PASS(每個 issue 的 backtick file path 都在 #55 commit 的 changed-files 列表)。

Scope Changes

• Cluster of 4 issues sharing 1 PR + 1 squash-merge commit 1557fbf(原 5 commits squashed: 4 implementation + 1 verify-fix)。
• Verify-stage findings:cross-model dissent caught accuracy issues Claude flat-passed(parser-behavior wording, scope claim narrowing, suppression description completeness)。
• 2 Codex HIGH on ### Notes non-KAC rejected as repo-convention false positives。

Blocking

• (none — issue CLOSED)

Commits

• 1557fbf: cluster: 4 docs follow-ups from archive-mail: support workspaces with nested communications layout and symlinked historical archives #49 / plugin-update: add Step 0 git-state preview + commit/push confirmation dialog before mutating origin #60 IDD lifecycles (cluster: 4 docs follow-ups from #49 / #60 IDD lifecycles #71) — squash merge
• (Pre-squash on cluster branch idd/cluster-docs-followups-49-60,already deleted post-merge)

[kiki830621]

Implementation Plan (cluster-PR mode)

This issue is part of a 4-issue docs 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:

• [docs] Backfill CHANGELOG [2.16.1] entry (sister concern from #49) #52 — Backfill CHANGELOG [2.16.1] entry in che-apple-mail-mcp
• [docs] archive-mail YAML message_id parser brittle — reduce 'schema diversity' claim or strengthen (sister concern from #49) #54 — Reduce "Resilient to schema diversity" claim in archive-mail.md Step 2.1
• [docs] README workspace pattern '100% backward compat' wording too strong (sister concern from #49) #55 — Soften "100% backward compat" wording in che-apple-mail-mcp/README.md
• [docs] plugin-tools CHANGELOG [1.15.0] entry has placeholder date — backfill (tangential from #60) #64 — Backfill [1.15.0] placeholder date in plugin-tools/CHANGELOG.md + restore description detail

Branch: idd/cluster-docs-followups-49-60

Files & Changes (per-issue)

#52 (commit 1)

• plugins/che-apple-mail-mcp/CHANGELOG.md — insert ## [2.16.1] - 2026-05-09 block between current [2.17.0] and [2.16.0]. Section: ### Notes (bump-only). Content: ship binary v2.7.1 (cluster: 4 refactor/docs follow-ups from #49 / #60 IDD lifecycles #72 base64 fix + [refactor] Define IDD_ALL_UNATTENDED env var contract across idd-all + plugin-tools (sibling concern from #60) issue-driven-development#123 SQLite fast-path stderr logging + [enhancement] che-apple-mail-mcp session-start hook: PID validation + started_at comparison hardening (follow-up from #76) #66 .partial.emlx attachment fix) + tool count drift catch-up 44→47.

#54 (commit 2)

• plugins/che-apple-mail-mcp/commands/archive-mail.md — Step 2.1 properties block, replace "Resilient to schema diversity" claim with v2.6+ format-compatibility wording matching issue body's diff sketch. Pure docs (option A.1 per issue), no parser hardening (deferred).

#55 (commit 3)

• plugins/che-apple-mail-mcp/README.md — Workspace Patterns section, replace "100% backward compat" wording with explicit-pin / mid-migration distinction per issue body's diff sketch.

#64 (commit 4)

• plugins/plugin-tools/CHANGELOG.md — replace ## [1.15.0] - (date unknown — please fill in) placeholder with ## [1.15.0] - 2026-04-26. Backfill description per scope expansion: README Freshness Gate v2 (6 signals + 2 suppressions), component inventory drift / tool count drift / version history multi-version gap, cross-28-plugin audit.

Sequencing

4 disjoint files → 4 independent commits, any order. Choose simplest visual order: #52 → #54 → #55 → #64.

Decision Points (locked in)

• D1 — Cluster vs separate PRs: chose cluster because all 4 are pure docs, low review surface, batch-friendly. Separate PRs would create review fragmentation for marginal benefit.
• D2 — [docs] archive-mail YAML message_id parser brittle — reduce 'schema diversity' claim or strengthen (sister concern from #49) #54 scope: claim reduction only (Option A.1 per issue body); no parser hardening this PR. Defer until N≥3 user reports of manual-archive missed dedup.
• D3 — [docs] plugin-tools CHANGELOG [1.15.0] entry has placeholder date — backfill (tangential from #60) #64 scope: include description backfill (per scope expansion comment), not just date — same file, single edit.

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; manual review of diff before commit.
• CHANGELOG cross-version ordering ([docs] Backfill CHANGELOG [2.16.1] entry (sister concern from #49) #52) — verify [2.18.1] [2.18.0] [2.17.0] [2.16.1] [2.16.0] ordering after insert.
• changelog-validate 3-way sync — descriptions byte-equality check still applies; [docs] plugin-tools CHANGELOG [1.15.0] entry has placeholder date — backfill (tangential from #60) #64 only changes CHANGELOG, not plugin.json/marketplace.json (those still have v1.16.0 description, which is different from v1.15.0). 3-way sync is on latest entry, not historical entries — this PR doesn't change latest, no sync issue.

Out-of-scope

• Parser hardening for [docs] archive-mail YAML message_id parser brittle — reduce 'schema diversity' claim or strengthen (sister concern from #49) #54 (Option B in issue) — defer
• Other CHANGELOG drift across marketplace plugins — defer to plugin-deploy audit pass
• README Workspace Patterns rewrite beyond [docs] README workspace pattern '100% backward compat' wording too strong (sister concern from #49) #55 — defer

[kiki830621]

Implementation Complete

Checklist (synced from cluster Implementation Plan)

• plugins/che-apple-mail-mcp/README.md — Workspace Patterns section, replace "Detection 不會 fire,既有行為 100% backward compat。" with explicit-pin / mid-migration distinction → commit a89bca3

Cluster context

Part of 4-issue docs cluster sharing PR #71. Cluster branch idd/cluster-docs-followups-49-60.

Changes

• a89bca3: docs(che-apple-mail-mcp): soften '100% backward compat' Workspace Patterns wording (Refs [docs] README workspace pattern '100% backward compat' wording too strong (sister concern from #49) #55)

PR

#71

Verification

• ✅ Diff matches issue body's diff sketch
• ✅ New wording explicitly distinguishes the two cases (explicit-pin vs zero-config + multi-layout)
• ✅ Honest framing matches actual gate behavior shipped in v2.17.0

Scope Compliance

Single line change in README. No code/spec/strategy change.

Sister Bugs Filed

none surfaced.

Next: verification pending

/idd-verify --pr 71

[kiki830621]

Verify (via PR #71)

Result: PASS — all blocking findings resolved in fix commit c04f66d
Full report: #71 (comment)

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

[kiki830621]

Closing Summary

Problem

plugins/che-apple-mail-mcp/README.md Workspace Patterns section(added in #49)宣稱 detection 不 fire 時「既有行為 100% backward compat」。但實際:zero-config user with both communications/email/ AND correspondence/emails/ 同時存在含 *.md 的 mid-migration scenario 會被 ambiguity guard abort(這 IS a backward-compat change vs pre-v2.17 silently-pick-default behavior)。"100%" wording 過強。

Surfaced in /idd-verify PsychQuant/psychquant-claude-plugins#49 DA new finding。

Root Cause

#49 v2.17.0 implementation 加 ambiguity guard 是正確設計,但 README wording 沒 align — 把"avoidance via explicit-pin"框架成"100% no behavior change",忽略了 zero-config + multi-layout-coexist 的 abort path。Wording 不誠實 vs actual gate behavior。

Solution

Replace "Detection 不會 fire,既有行為 100% backward compat。" 為:

"已 explicit-pin 的 workspace 行為不變;zero-config 且 communications/email/ 與 correspondence/emails/ 同時存在含 *.md 的 mid-migration workspace 會被 ambiguity guard flag,要求 explicit pin(避免半實作狀態的 dedup-index split-brain)。"

明確 distinguish:

• Explicit-pin workspaces:behavior unchanged(true)
• Zero-config + multi-layout:ambiguity guard flags for explicit pin(documented honestly)

Verification

• 6-AI cluster verify on PR cluster: 4 docs follow-ups from #49 / #60 IDD lifecycles #71 — [docs] README workspace pattern '100% backward compat' wording too strong (sister concern from #49) #55 single PASS first round(both Claude reviewer + Codex GPT-5.5 agreed,no fix needed mid-cycle)
• Empirically aligns with v2.17.0 ambiguity guard implementation(SKILL.md L138-146)
• Full verify report: PR PsychQuant/psychquant-claude-plugins#71 issuecomment-4415171847

Changes

• a89bca3 — docs(che-apple-mail-mcp): soften '100% backward compat' Workspace Patterns wording (Refs [docs] README workspace pattern '100% backward compat' wording too strong (sister concern from #49) #55)
• 1557fbf — cluster squash merge

Cluster context

Part of 4-issue docs cluster (PR #71)。Single round PASS — 不需 verify-fix。Sister issues #52 #54 #64 各自獨立 close。

Closing Follow-ups Filed (v2.45.0+ #527)

(none — no orphan mentions in closing summary)

Trigger-phrase scan hits: all classified as cross-linked context or CONSTRAINT-with-trigger-condition (IC_R011 §3 exempt) — no separate filings warranted.