docs(spec): cite Cursor-native hook fail-closed validation and Claude-import coexistence as req-tg-016/017

Adds Section 8.5.9 to the OpenAPM v0.1 spec documenting the already-shipped
Cursor-native hook installation behavior from this PR: fail-closed
conversion validation (req-tg-016) and Claude-import-coexistence rejection
(req-tg-017, both install orders). Narrowly bound to the accepted
Cursor-native(+Claude-import) capability only, not a universal
target-native obligation. Includes vendor-grounded editorial note
(cursor.com/docs/hooks, cursor.com/docs/reference/third-party-hooks)
distinguishing APM's own conservative conversion/safety policy from
vendor-documented defaults (vendor default is merge-not-reject; vendor
top-level shape is not documented as closed).

Updates Section 8.7 and 11.3.2 enumerations, Appendix C (2 new rows,
total 127 statements / 122 MUST), the requirements manifest, the
0.1.44 (proposed) revision-history row, regenerated CONFORMANCE
artifacts, and new drift-sentinel conformance tests
(tests/spec_conformance/test_cursor_hook_reqs.py) citing the
already-existing, already-passing behavioral integration tests.

Folds 4 round-1 findings from the real apm-spec-guardian 4-persona panel
(spec-swagger-editor, spec-oci-editor, spec-pkgmgr-editor,
spec-tag-architect; synthesizer ship_decision=fold_and_ship,
shocked_meter_avg=8.0, 0 blockers across all 4 panels):
- req-tg-017: defines the "observable overlap" predicate normatively
  (non-empty hook-event-identifier intersection after alias
  normalization), closing a 4/4-panel-convergent second-implementer
  reproducibility gap.
- req-tg-016: adds a SHOULD-level sentence requiring implementations to
  document/expose their accepted source-format vocabulary, so
  conformance claims are independently verifiable.
- Editorial note: drops the stale "eight" alias count (staleness magnet
  in informative text).
- 0.1.44 revision row: adds a one-line clarification that revision label
  0.1.43 and requirement id req-tg-015 are reserved by a concurrent
  sibling unit (PR #3150) on its own branch, not an unintentional gap.

Deferred to v0.1.1 (not folded here, too heavy for a surgical mechanical
fold): a machine-readable accepted-vocabulary artifact, and a stale-
partial-artifact disposition clause for req-tg-016. Rejected: the
stale cursor_preflight_done cache-bypass surface (out of scope, requires
a src/apm_cli/** change this unit does not authorize) and the full
vocabulary-artifact proposal (superseded by the lighter SHOULD-sentence
folded above).

No src/apm_cli/** changes. No spec waiver. Statement count unchanged at
127 (122 MUST, 5 SHOULD) -- this fold is prose-only, no new anchors.
tests/spec_conformance/ re-verified: 293 passed, 2 skipped (orphan 4-way
invariant intact). Closes the Spec conformance gate gap for PR #3149 /
issue #3129.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

CHANGELOG.md

@@ -14,6 +14,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Codex agent conversion preserves native `model` and `model_reasoning_effort` settings and warns about dropped metadata instead of silently losing it. (#3150)
+### Added
+
+- OpenAPM v0.1 spec: documented the already-shipped Cursor-native hook installation fail-closed conversion validation and Claude-import-coexistence rejection as [req-tg-016] and [req-tg-017] (Section 8.5.9). (#3149)
 
 ## [0.33.0] - 2026-10-02
 

CONFORMANCE.json

@@ -1555,12 +1555,34 @@
       "tests": [
         "tests/spec_conformance/test_manifest_reqs.py::test_codex_native_model_settings_preserved_and_dropped_metadata_bounded"
       ]
+    },
+    {
+      "conformance_class": "consumer",
+      "id": "req-tg-016",
+      "keyword": "MUST",
+      "section": "8.5.9",
+      "status": "active",
+      "test_count": 1,
+      "tests": [
+        "tests/spec_conformance/test_cursor_hook_reqs.py::test_cursor_native_fail_closed_conversion_clause_persists_in_spec"
+      ]
+    },
+    {
+      "conformance_class": "consumer",
+      "id": "req-tg-017",
+      "keyword": "MUST",
+      "section": "8.5.9",
+      "status": "active",
+      "test_count": 1,
+      "tests": [
+        "tests/spec_conformance/test_cursor_hook_reqs.py::test_cursor_claude_import_overlap_rejection_clause_persists_in_spec"
+      ]
     }
   ],
   "spec_version": "v0.1.1",
   "summary_by_class": {
     "consumer": {
-      "active": 92,
+      "active": 94,
       "skipped": 1,
       "unbound": 0,
       "xfail": 0
@@ -1584,5 +1606,5 @@
       "xfail": 0
     }
   },
-  "total_requirements": 126
+  "total_requirements": 128
 }

CONFORMANCE.md

@@ -33,7 +33,7 @@ APM claims the proposed deployed-prompt-audit capability (req-pl-019, req-pl-020
 | Class | Active | Skipped | Xfail | Unbound |
 |-------|-------:|--------:|------:|--------:|
 | Producer | 12 | 0 | 0 | 0 |
-| Consumer | 92 | 1 | 0 | 0 |
+| Consumer | 94 | 1 | 0 | 0 |
 | Registry | 1 | 0 | 0 | 0 |
 | Governance | 20 | 0 | 0 | 0 |
 
@@ -167,6 +167,8 @@ APM claims the proposed deployed-prompt-audit capability (req-pl-019, req-pl-020
 | [req-tg-013](docs/src/content/docs/specs/openapm-v0.1.md#req-tg-013) | MUST | 8.5.7 | consumer | active | 7 | - |
 | [req-tg-014](docs/src/content/docs/specs/openapm-v0.1.md#req-tg-014) | MUST | 8.5.8 | consumer | active | 1 | - |
 | [req-tg-015](docs/src/content/docs/specs/openapm-v0.1.md#req-tg-015) | MUST | 8.5.1 | consumer | active | 1 | - |
+| [req-tg-016](docs/src/content/docs/specs/openapm-v0.1.md#req-tg-016) | MUST | 8.5.9 | consumer | active | 1 | - |
+| [req-tg-017](docs/src/content/docs/specs/openapm-v0.1.md#req-tg-017) | MUST | 8.5.9 | consumer | active | 1 | - |
 
 ## Waivers
 

docs/public/specs/manifests/openapm-v0.1.requirements.yml

@@ -465,6 +465,16 @@ requirements:
     section: "8.5.1"
     conformance_class: consumer
     notes: "a conforming consumer providing the Codex-native agent conversion capability preserves a source-declared model or model_reasoning_effort string value in its native top-level placement, leaves either field absent when absent from the source, diagnoses a non-string source value by field name without including that value, and emits a diagnostic bounded on dropped-field count (at least one shown when any are dropped), per-field name length, and ASCII-sanitized field-name display (never the value) for any other dropped, non-capability-restriction frontmatter field"
+  - id: req-tg-016
+    keyword: MUST
+    section: "8.5.9"
+    conformance_class: consumer
+    notes: "a Cursor-native hook installation implementation fails closed (no partial write) when converting a source-declared hook configuration whose event, top-level key, or handler field falls outside the accepted Cursor-native vocabulary, emitting an actionable diagnostic naming the unrecognized value(s)"
+  - id: req-tg-017
+    keyword: MUST
+    section: "8.5.9"
+    conformance_class: consumer
+    notes: "a Cursor-native hook installation implementation detects, before writing, an observable overlap with an in-effect Claude-settings hook import for either install order, and rejects the write with an actionable diagnostic rather than merging, redirecting, or broadening accepted input, without altering the Claude import's own settings"
   - id: req-pr-006
     keyword: MUST
     section: "8.1"

docs/src/content/docs/specs/openapm-v0.1.md

@@ -136,7 +136,7 @@ between the companion corpus and the implementation.
 
 ### 1.3 Document conventions
 
-- OpenAPM v0.1 carries **126 normative statements (121 MUST, 5 SHOULD)** indexed in
+- OpenAPM v0.1 carries **128 normative statements (123 MUST, 5 SHOULD)** indexed in
   [Appendix C](#appendix-c-index-of-normative-statements).
 - All on-disk files defined by this specification are **YAML 1.2**
   parsed under the safe subset defined in
@@ -2977,6 +2977,58 @@ manifest restriction, it MUST serialize only the supported subset using target
 identifiers whose replay selects the same runtimes; it MUST NOT persist an
 unsupported member or remap one to a different supported runtime.
 
+#### 8.5.9 Cursor-native hook installation: fail-closed validation and Claude-import coexistence
+
+<a id="req-tg-016"></a>
+**[req-tg-016]** A conforming consumer implementation that provides Cursor-native
+hook installation MUST fail closed when converting a source-declared hook
+configuration into that Cursor-native format: if any source-declared event,
+top-level configuration key, or handler field falls outside the vocabulary of
+events, top-level keys, and handler fields the implementation accepts for
+Cursor-native hooks, the implementation MUST NOT write the Cursor-native hook
+artifact (zero bytes, no partial file) and MUST emit an actionable diagnostic
+naming the unrecognized value(s). Implementations SHOULD document or
+programmatically expose the set of accepted source-format identifiers so that
+conformance claims are independently verifiable.
+
+<a id="req-tg-017"></a>
+**[req-tg-017]** A conforming consumer implementation that provides Cursor-native
+hook installation, when the project or user scope also has a Claude-settings
+hook import in effect for the same scope, MUST detect before writing whether
+installing or retaining the Cursor-native hook configuration would create or
+extend an observable overlap with that Claude-imported hook configuration, for
+both install orders (Claude-import-first and Cursor-native-first). On a
+detected overlap the implementation MUST reject the write with an actionable
+diagnostic rather than merge, redirect, or broaden either side's accepted
+input, and MUST NOT alter the Claude import's own settings. For the purposes
+of this requirement, "observable overlap" is defined as a non-empty
+intersection between the set of hook-event identifiers claimed by the
+Cursor-native configuration and those claimed by the in-effect Claude-settings
+import, evaluated after alias normalization.
+
+> **Editorial note.** The event vocabulary, the Claude-to-Cursor event
+> aliases, and the two-key (`version`, `hooks`) top-level shape this
+> implementation validates are drawn from Cursor's own hook reference and
+> third-party-hook reference as published at
+> `https://cursor.com/docs/hooks` and
+> `https://cursor.com/docs/reference/third-party-hooks` (fetched 2026-10-03).
+> As with [req-tg-009]'s target-native capability encodings, these concrete
+> vendor-specific vocabularies are intentionally kept out of the normative
+> text above; a future harness implementing the same Cursor-native capability
+> may accept a different, equally fail-closed vocabulary as the vendor
+> surface evolves. The vendor reference also documents a `prompt` handler
+> kind alongside `command`; this note does not assert that the accepted
+> vocabulary covers every hook feature Cursor documents, only that whatever
+> vocabulary an implementation does accept is enforced fail-closed. The
+> rejection in [req-tg-017] is an APM consumer-side safety policy, not a
+> reflection of Cursor's own documented default: the vendor's third-party-hook
+> reference states that when hooks exist in multiple locations "All matching
+> hooks from every source run" (merge, not reject). Likewise, the unknown-key
+> rejection in [req-tg-016] is this implementation's own conservative
+> conversion policy; the cited vendor example shows only `version` and
+> `hooks` as top-level keys but does not itself document the top-level shape
+> as closed to extension.
+
 ### 8.6 Per-target primitive support (informational)
 
 The matrix of which primitive types each target supports is
@@ -2995,7 +3047,9 @@ without a spec revision. The current matrix is in the companion
   [req-tg-010](#req-tg-010), [req-tg-011](#req-tg-011),
   [req-tg-012](#req-tg-012), [req-tg-013](#req-tg-013),
   [req-tg-014](#req-tg-014), [req-tg-015](#req-tg-015),
-  [req-pr-006](#req-pr-006), [req-pr-007](#req-pr-007).
+  [req-pr-006](#req-pr-006),
+  [req-pr-007](#req-pr-007), [req-tg-016](#req-tg-016),
+  [req-tg-017](#req-tg-017).
 
 ---
 
@@ -3642,6 +3696,7 @@ conformance statement identifying:
 [req-tg-010](#req-tg-010), [req-tg-011](#req-tg-011),
 [req-tg-012](#req-tg-012), [req-tg-013](#req-tg-013),
 [req-tg-014](#req-tg-014), [req-tg-015](#req-tg-015),
+[req-tg-016](#req-tg-016), [req-tg-017](#req-tg-017),
 [req-sc-001](#req-sc-001),
 [req-sc-002](#req-sc-002), [req-sc-003](#req-sc-003),
 [req-sc-004](#req-sc-004), [req-sc-005](#req-sc-005),
@@ -4105,6 +4160,8 @@ renumbering of conformance classes.
 | [req-tg-013](#req-tg-013)                | MUST    | 8.5.7   | consumer    |
 | [req-tg-014](#req-tg-014)                | MUST    | 8.5.8   | consumer    |
 | [req-tg-015](#req-tg-015)                | MUST    | 8.5.1   | consumer    |
+| [req-tg-016](#req-tg-016)                | MUST    | 8.5.9   | consumer    |
+| [req-tg-017](#req-tg-017)                | MUST    | 8.5.9   | consumer    |
 | [req-sc-001](#req-sc-001)                | MUST    | 10.4    | consumer    |
 | [req-sc-002](#req-sc-002)                | MUST    | 10.9    | consumer    |
 | [req-sc-003](#req-sc-003)                | MUST    | 10.3    | consumer    |
@@ -4124,7 +4181,7 @@ renumbering of conformance classes.
 | [req-cf-001](#req-cf-001)                | MUST    | 12.5    | consumer    |
 | [req-cf-002](#req-cf-002)                | MUST    | 12.3    | consumer    |
 
-**Total normative statements: 126** (121 MUST, 5 SHOULD).
+**Total normative statements: 128** (123 MUST, 5 SHOULD).
 
 ---
 
@@ -4177,6 +4234,7 @@ renumbering of conformance classes.
 | 0.1.41  | 2026-09-09 | Alias containment and lock-replay contract for PR #2901. Added [req-mf-025] (Section 4.3.2, consumer MUST), the optional lock-entry `alias` field, and conformance coverage. Under Section 9.2 this is an additive optional field and a defensive definition of previously unspecified alias behavior, not behavior-neutral errata: unsafe or reserved aliases can newly fail; valid dotted aliases remain accepted; surrounding whitespace is canonicalized; recorded aliases determine replay placement; absent aliases retain the unaliased layout. Source identity and permitted local source paths are unchanged. Older readers preserving the unknown field do not thereby implement placement support. Selects distinct 0.1.41 schema publication identities without changing published v0.1 URLs or bytes; Section 9.3 remains pending (see Appendix A). Sections 1.3, 4.9, 5.2, 10.7, 10.11, 11.3.2, and Appendix C updated. Statement count: 122 -> 123 (118 MUST, 5 SHOULD). |
 | 0.1.42 (proposed) | 2026-09-30 | Optional deployed-prompt audit capability for PR #2962. Added conditional governance [req-pl-019] and [req-pl-020] in Section 6.8.1, both enumerations, Appendix C, requirements manifest and behavioral conformance coverage. Under Section 9.2 this is a new opt-in conformance capability, not behavior-neutral errata or a reinterpretation of an existing obligation: implementations not claiming it acquire no new required feature. APM claims it; newly discovered prompt findings and incomplete native coverage can newly fail default and CI audits, command-only content remains non-failing, and protected remediation is refused before writes. No schema, lockfile version, existing mandatory feature, drift-policy or ownership rule changes. Section 9.3 reviewer approvals and public comment period remain pending; this proposal is not evidence of adoption. Statement count: 123 -> 125 (120 MUST, 5 SHOULD). |
 | 0.1.43 (proposed) | 2026-10-03 | Codex-native agent model preservation and bounded dropped-metadata diagnostic for PR #3150 (closes #3126). Added [req-tg-015] (Section 8.5.1, consumer MUST): a conforming consumer providing the Codex-native agent conversion capability MUST preserve a source-declared `model` or `model_reasoning_effort` string value in its native top-level placement, MUST leave either field absent when absent from the source, MUST diagnose a non-string value by field name without including that value, and MUST emit a diagnostic bounded on both dropped-field count and per-field name length (never the value) for any other dropped, non-capability-restriction frontmatter field. Under Section 9.2 this is a new opt-in conformance capability scoped to consumers providing the Codex-native agent conversion capability, not behavior-neutral errata: it does not require or imply preservation of any other `config.toml`-native key and does not define behavior for any other conversion target. Implementations not providing Codex-native agent conversion acquire no new required feature. No schema, lockfile version, existing mandatory feature, drift-policy or ownership rule changes. Section 9.3 reviewer approvals and public comment period remain pending; this proposal is not evidence of adoption. Section 8.7, Section 11.3.2, and Appendix C updated. Statement count: 125 -> 126 (121 MUST, 5 SHOULD). |
+| 0.1.44 (proposed) | 2026-10-03 | Spec-citation fold for already-accepted Cursor-native hook installation (PR #3149, closes issue #3129's conformance gap). Added [req-tg-016] (Section 8.5.9, consumer MUST): fail-closed validation of out-of-vocabulary events, top-level keys, and handler fields when converting into the Cursor-native hook format. Added [req-tg-017] (Section 8.5.9, consumer MUST): pre-write detection and rejection of a Cursor-native-plus-Claude-import hook overlap, for both install orders, without altering the Claude import's own settings. Both anchors are bound specifically to the already-accepted Cursor-native (and Cursor-native-plus-Claude-import) capability, not a universal target-native or cross-target obligation. Section 8.7, Section 11.3.2, and Appendix C updated. Under Section 9.2 this is a defensive citation of previously unspecified fail-closed/coexistence behavior already shipped and tested in PR #3149, not a new mandatory feature for implementations that do not provide this capability. Section 9.3 reviewer approvals and public comment period remain pending; this proposal is not evidence of adoption. Statement count: 125 -> 127 (122 MUST, 5 SHOULD). Revision label `0.1.43` and requirement id [req-tg-015] are reserved by a concurrent sibling unit on a separate branch and are not assigned here. |
 
 Errata (none at publication).
 

tests/spec_conformance/test_cursor_hook_reqs.py

@@ -0,0 +1,60 @@
+"""Cursor-native hook installation conformance -- sec.8.5.9.
+
+req-tg-016 and req-tg-017 are the spec-citation fold for PR #3149's
+already-shipped Cursor-native hook capability: fail-closed conversion
+validation and Claude-import-coexistence rejection. These are
+silent-deletion detectors that pin the normative phrasing in place;
+the actual behavioral proof is the already-existing, already-passing
+integration suite named in the editorial note below (not duplicated
+here), consistent with this directory's drift-sentinel pattern for
+requirements backed by a real shipped implementation rather than a
+schema or fixture.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from tests.spec_conformance._helpers import assert_spec_contains
+
+
+@pytest.mark.req("req-tg-016")
+def test_cursor_native_fail_closed_conversion_clause_persists_in_spec() -> None:
+    """Silent-deletion detector for the req-tg-016 normative clause.
+
+    Behavioral proof (not duplicated here):
+    tests/unit/integration/test_cursor_hook_native_contract.py::
+    test_unrepresentable_hooks_fail_without_native_or_script_writes,
+    ::test_cursor_install_emits_native_events_and_flat_handlers.
+    """
+    assert_spec_contains(
+        "MUST fail closed when converting a source-declared hook\n"
+        "configuration into that Cursor-native format",
+        "the implementation MUST NOT write the Cursor-native hook\n"
+        "artifact (zero bytes, no partial file)",
+        "MUST emit an actionable diagnostic\nnaming the unrecognized value(s)",
+    )
+
+
+@pytest.mark.req("req-tg-017")
+def test_cursor_claude_import_overlap_rejection_clause_persists_in_spec() -> None:
+    """Silent-deletion detector for the req-tg-017 normative clause.
+
+    Behavioral proof (not duplicated here):
+    tests/unit/integration/test_cursor_hook_native_contract.py::
+    test_import_overlap_refused_in_either_install_order,
+    ::test_import_locations_preserved_and_overlap_rejected,
+    ::test_unapproved_hooks_do_not_enter_cursor_preflight;
+    tests/integration/test_package_target_hook_routing_e2e.py::
+    test_package_target_transition_repairs_cursor_and_uninstall_preserves_user_hook,
+    ::test_failed_restricted_update_preserves_existing_hook_state;
+    tests/integration/test_cursor_hook_lifecycle.py::
+    test_cursor_installed_cli_contract.
+    """
+    assert_spec_contains(
+        "for\nboth install orders (Claude-import-first and Cursor-native-first)",
+        "MUST reject the write with an actionable\n"
+        "diagnostic rather than merge, redirect, or broaden either side's accepted\n"
+        "input",
+        "MUST NOT alter the Claude import's own settings",
+    )