// Package counterfactual defines the standardized data structure for
// reverse-thinking deliverables produced before non-trivial tool calls.
//
// # Why this package exists
//
// CLAUDE.md article 1 (reverse thinking) requires that any non-trivial
// design choice be challenged from the opposite side before commit. The
// soft skill at ~/.claude/skills/reverse-think/ runs MiniMax to produce
// hidden_assumptions / failure_scenarios / verdict / verdict_reason.
// Until v0.3-dev that produce was free-form text. counterfactual locks
// the schema so the same shape can be (a) persisted on staging.Record,
// (b) replayed through evolve.LogReplayer, (c) audited cross-tenant.
//
// The package is opt-in: nothing in core/pkg/engine forces a Deliverable
// to exist. The hook layer (platform/common/safetychain) decides when to
// invoke the reverse-think skill, based on tools.Metadata.RequiresReverseThinking.
// Default off = zero latency / zero LLM call overhead on hot paths.
//
// # Boundary with staging / validator / evolve
//
//   - staging.Record: a Deliverable is one signal a Validator may consult,
//     stored in Record.Metadata under MetadataKey. counterfactual itself
//     is not a Validator and emits no Verdict on staged diffs.
//   - validator.Verdict: scoped to "is this staged decision safe to commit",
//     consumed by staging.Engine. A Deliverable is upstream evidence, not
//     a verdict.
//   - evolve.Reflector: counterfactual.Deliverable.AsReplayEvent (commit 4)
//     adapts a Deliverable into evolve.ReplayEvent so reverse-thinking
//     conclusions can be replayed against real KPI feedback. evolve does
//     not import counterfactual; counterfactual imports evolve to provide
//     the adapter (one-way dependency, mirrors reflector umbrella shape).
//
// # 反事实包: 反向思维五步的标准化数据结构
//
// CLAUDE.md 原则 1 (反向思维) 规定任何非平凡设计决策在 commit 前都要从
// 反面挑战一遍. 当前 ~/.claude/skills/reverse-think/ 软性 skill 跑 MiniMax
// 产出 hidden_assumptions / failure_scenarios / verdict / verdict_reason,
// 但产出形态是自由文本. v0.3-dev 起 counterfactual 包锁定 schema, 让同一
// 结构可以 (a) 落到 staging.Record 元数据 / (b) 经 evolve.LogReplayer 重放 /
// (c) 跨租户审计.
//
// 本包是 opt-in: core/pkg/engine 不强制 Deliverable 存在. hook 层
// (platform/common/safetychain) 看 tools.Metadata.RequiresReverseThinking
// 决定何时触发反向思维 skill. 默认关闭 = 热路径 0 延迟 / 0 LLM 调用开销.
//
// # 与 staging / validator / evolve 边界
//
//   - staging.Record: Deliverable 是 Validator 可参考的一种信号, 存于
//     Record.Metadata 下 MetadataKey 这个 key. counterfactual 本身不是
//     Validator, 不对 staged diff 出 Verdict.
//   - validator.Verdict: 作用域是 "此 staged 决策是否可 commit",
//     由 staging.Engine 消费. Deliverable 是上游证据, 不是 Verdict.
//   - evolve.Reflector: counterfactual.Deliverable.AsReplayEvent (commit 4)
//     把 Deliverable 适配成 evolve.ReplayEvent, 让反向思维结论可以与真实
//     KPI 反馈一起重放学习. evolve 不导入 counterfactual; counterfactual
//     导入 evolve 提供 adapter (单向依赖, 与 reflector umbrella 模式一致).
//
// # Reference files
//
//	deliverable.go     -- Deliverable struct + Verdict / Step constants
//	deliverable_test.go -- JSON roundtrip + Validate edge cases
//	replay_event.go    -- evolve.ReplayEvent adapter (commit 4)
package counterfactual