[FEATURE] Define OpenAPM hook semantics and replace pairwise hook translation

[danielmeppiel]

Is your feature request related to a problem? Please describe.
APM hook integration accepts vendor-shaped inputs and uses target-specific branches without a neutral semantic model. PR #2097 and PR #2095 expose the maintenance and neutrality cost: Claude structural normalization and Kiro v1 rendering currently extend a raw-dictionary, vendor-pivot pipeline.

Describe the solution you'd like
Deliver the hooks proving slice from docs/superpowers/specs/2026-07-10-openapm-standards-first-translation-design.md within one release cycle:

• Amend the next OpenAPM specification with a small portable hook subset.
• Add immutable HookIR, named import adapters, capability validation, and a target-renderer Strategy registry.
• Preserve the existing deny-wins executable trust gate before rendering.
• Keep legacy inputs compatible with explicit loss/default reporting.
• Rework PR fix(hooks): normalize flat entries for Claude #2097 as the first loss-accounted Claude render.
• Rework PR fix(hooks): emit Kiro v1 hook documents #2095 as the first Kiro v1 render without a Claude pivot or _kiro_* side channels.
• Split Kiro-native import into a separate follow-up.
• Require hermetic E2E, mutation-break, conformance, final ship_now, and exact-SHA green CI evidence.

Describe alternatives you've considered
Adopt Claude hooks as APM's canonical schema, ship each vendor mapping independently, or stop translating hooks. These respectively violate neutrality, compound maintenance, or abandon portability.

Additional context
Related: #2062, #2071, PR #2097, PR #2095.

If the foundation misses the release-cycle window, the two live bugs may land as minimal named compatibility bridges and must move to HookIR in the following minor release.

[sheilagithub]

Following this — the HookIR + loss-reporting direction makes
a lot of sense. While mapping some capabilities onto apm I gathered per-harness
hook data that might be useful input when you scope the portable subset, so
sharing it here in case it helps.

The thing I ran into: only PreToolUse/PostToolUse carry through apm
today, so session/turn lifecycle hooks stay stuck as per-harness plugins — even
though the same semantic event seems to exist on almost every target under a
different name. Verified against each harness's official hook docs (2026-07-12):

Semantic event	Targets	Per-harness names
Prompt-submit (pre-prompt)	7/7	UserPromptSubmit (Claude/Codex/Kiro) · userPromptSubmitted (Copilot) · beforeSubmitPrompt (Cursor) · BeforeAgent (Gemini) · pre_user_prompt (Windsurf)
Turn-end	7/7	Stop (Claude/Codex/Kiro) · stop (Cursor) · agentStop (Copilot) · AfterAgent (Gemini) · post_cascade_response (Windsurf)
Session-start	6/7	all but Windsurf
Session-end	4/7	Claude/Copilot/Cursor/Gemini (Codex/Kiro fold into turn-end)
Compaction	5/7	Claude/Codex/Copilot/Cursor + Gemini PreCompress; a post-compact event only on Claude/Codex

The prompt-submit and turn-end events being 7/7 (and session-start 6/7) is what
stood out — that felt like the naming divergence HookIR is meant to absorb, with
the odd gap (e.g. Windsurf has no session-start) handled by the loss reporting
in #2110.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/multi-target
area/distribution
type/feature
status/accepted
status/triaged
priority/high

Note: area/docs-site was considered (new HookIR primitive concept will need a documentation page) but omitted to stay within the 6-label cap. Maintainer may add it when the implementation PR opens.

Milestone

null

No open milestones were detectable at triage time. Maintainer should assign the appropriate milestone when scoping this work.

Suggested next action

Amend the next OpenAPM specification with the portable hook subset, then open a PR implementing HookIR and the Strategy registry -- gated on #2110 (transformation contract) landing first.

Suggested issue comment

Thank you for filing this, @danielmeppiel. The hooks proving slice correctly lands as type/feature + status/accepted + priority/high.

The proposed approach -- HookIR as a neutral semantic model, named import adapters, capability validation, a target-renderer Strategy registry, and reworked Claude and Kiro v1 renders as the first loss-accounted outputs -- is well-aligned with the standards-first translation design.

A few notes for the implementation PR:

• This work depends on [ARCHITECTURE] Add the OpenAPM transformation and loss-report contract #2110 (the transformation and loss-report contract) landing first. HookIR should adopt RenderResult from that foundation.
• The deny-wins trust gate must remain in the critical path before rendering.
• The Kiro-native import split is correctly scoped as a follow-up; do not expand scope here.
• The hermetic E2E, mutation-break, conformance, and exact-SHA CI evidence requirement should be explicit acceptance criteria on the PR.

Next step: spec amendment first (define the portable hook subset in the OpenAPM specification), then the HookIR implementation PR referencing the spec.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user-facing surface is consistent hook behavior across targets: a hook defined once in the portable subset should render correctly for Claude and Kiro without per-target branching in user code. The Strategy registry abstraction is the right pattern. The loss reporting ensures users know when a hook attribute is dropped at render time rather than discovering it through broken behavior. Strongly aligned with the npm/cargo mental model APM commits to.

Supply Chain Security Expert -- Risk-Surface Reviewer

The deny-wins executable trust gate is explicitly mentioned and must remain in the critical path before any rendering step. The named import adapters and capability validation layer are the right place to enforce trust boundaries (only validated, capability-declared hooks reach the renderer). No additional security label is needed beyond the existing labels; the trust gate is an implementation constraint, not a new risk surface.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- danielmeppiel is a collaborator and the primary driver of this initiative; no tone adjustment needed.

Python Architect -- Architecture Reviewer

The HookIR + Strategy registry pattern is the correct abstraction. Cross-cutting impact: all target integrators that currently handle hooks via vendor-pivot will need to be reworked to the Strategy pattern. The implementation PR must include a clear migration boundary (what is the old path, what is the new path, what is the compatibility shim if any). The rework of PR #2097 (Claude render) and PR #2095 (Kiro v1 render) as first loss-accounted renders is the right proving slice. status/accepted is correct; the design doc provides the necessary specification.

Doc Writer -- Documentation Reviewer

The new HookIR primitive concept and the portable hook subset in the OpenAPM specification will need a user-facing documentation page explaining the hook authoring model (what fields are portable, what targets support what capabilities, and how loss is reported). area/docs-site was omitted from the label set to stay within the 6-label cap but is recommended as a secondary label for the implementing PR.

APM CEO -- Triage Arbiter

This is the primary deliverable of the standards-first translation initiative. priority/high is correct. The dependency on #2110 is correctly noted in the issue; the panel confirms it. The spec amendment before code is the right sequencing. Accept and prioritize, conditioned on #2110 landing first. Milestone deferred to maintainer.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/multi-target", "area/distribution"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Amend the OpenAPM spec with the portable hook subset, then open a HookIR implementation PR gated on #2110 landing first.",
  "comment_markdown": "See above."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · 150.3 AIC · ⌖ 7.64 AIC · ⊞ 9.2K · ◷