docs: codify the policy/behavioral hook-classification rubric

[kyle-sexton]

No linked issue

Summary

Promotes the #2021 hook-surface audit's classification method into standing doctrine, so downstream consumer repos can run the same pass over their own hook surfaces at each generation-triggered ablation.

Fix

Adds a "Classifying a hook" subsection to docs/PLUGIN-PHILOSOPHY.md's Instruction economy section: the two-axis rubric (mechanism x class), the mechanism-never-implies-class rule, the hybrid trim-not-delete rule, the ground-truth-oracle carve-out (behavioral purpose + non-derivable oracle = keep), and the config-disable-first remediation order. This records the classification-authority decision on #2021: standing playbook rubric, not one-time audit.

Verification

Docs-only change; markdownlint clean on edit; no plugin manifests, catalog, or cheat-sheet affected.

Related

Refs #2021 (the audit this rubric generalizes), #2009, docs/PLUGIN-PHILOSOPHY.md "Instruction economy".

🤖 Generated with Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

Claude finished @kyle-sexton's task in 2m 56s —— View job

---

Review: PR #2033 — docs: codify the policy/behavioral hook-classification rubric

• Gather context (diff, CLAUDE.md, PLUGIN-PHILOSOPHY.md, related conventions)
• Understand the request (code review of a docs-only addition)
• Review the new "Classifying a hook" subsection for correctness/alignment
• Post findings

Summary

Docs-only change (docs/PLUGIN-PHILOSOPHY.md +29/-0), adding a "Classifying a hook" subsection under "Instruction economy." Content-wise the rubric is sound and grounded in things that actually exist elsewhere in this repo:

• The durable-tier rule it extends is the existing bullet at
  L492-496.
• The config-disable-first remediation order it prescribes has real backing in
  docs/conventions/hook-config-delivery/README.md (channel F / kill-switch pattern), so it isn't inventing a mechanism that doesn't exist.
• The security carve-out it references ("below") is the very next paragraph
  (L527-530) — correct forward reference.
• This is the file's first ### (H3) heading; it nests cleanly under the existing "Instruction economy" ## section and doesn't disturb any TOC (the file has none) or numbering.

Two prose-clarity issues left as inline comments, both fixable without touching the underlying rubric:

1. L500-502 — the opening sentence is a fragment (subject "The standing rubric…" never gets a finite verb).
2. L523 — "the evidence gate above" is an implicit, easy-to-miss cross-reference to the differently-named "Evidence-gated additions" bullet, which is actually about a different concern (addition bar, not removal order).

Not independently verified

• The claim "44 wired hook entries in the 2026-08 audit (issue Hook-surface classification: 44 wired hooks classified policy vs behavioral (report-only) #2021)" — I could not fetch issue Hook-surface classification: 44 wired hooks classified policy vs behavioral (report-only) #2021 in this environment (no gh/network access available to this review lane), so this is author-claimed and unverified by me.
• The PR body's "markdownlint clean on edit" claim — I don't have markdownlint/markdownlint-cli2 available in this sandbox to independently confirm; taking it as author-claimed, not verified.

Scope check (CLAUDE.md fresh-docs mandate)

This change describes a classification methodology for existing hooks, not a change to a hook contract, manifest schema, or documented harness behavior itself — no new claims about hooks.json schema, exit-code semantics, or userConfig delivery are introduced. I don't think the fresh-docs mandate's citation requirement is triggered here, since no harness-behavior fact is being asserted or changed.

No plugin manifests, catalog, or contract-surface files are touched, consistent with the PR's own verification note.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 63fe5e48ac

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Claude has reviewed this PR 2 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

Claude finished @kyle-sexton's task in 1m 22s —— View job

---

Review: PR #2033 — docs: codify the policy/behavioral hook-classification rubric

• Gather context (diff since last review, follow-up commit f3409ed)
• Check whether the two prose issues flagged in the prior review were addressed
• Review the new content for correctness/alignment
• Post findings

Summary

Follow-up commit f3409ed addresses both prose issues from the earlier review pass — re-reviewed against the current head:

1. Sentence fragment (was L500-502) — fixed. The opening is now two complete sentences ("This is the standing rubric the classification the durable-tier rule requires... It was first applied across this marketplace's 44 wired hook entries...").
2. Ambiguous "evidence gate above" (was L523) — fixed. It now names the bullet explicitly: "Remediation applies the same evidentiary rigor to removal that Evidence-gated additions above requires for addition" (L523), resolving cleanly to the L477 bullet.

No new issues found in the fix commit. The section's cross-references still check out against the current file:

• The durable-tier rule it extends is L492-496.
• "the security carve-out below" (L526) correctly points to the very next paragraph (L528-531).
• "config-disable first where a kill switch exists" has real backing in docs/conventions/hook-config-delivery/, confirmed present in this checkout.
• Minor correction to the prior review's own claim: this is not the file's first ### heading overall (### Dispatch ladder etc. appear later under "Delegation mechanics"), but it is the first one encountered reading top-to-bottom and nests correctly under "## Instruction economy" — doesn't affect the content, just noting for the record.

Not independently verified

• "44 wired hook entries in the 2026-08 audit (issue Hook-surface classification: 44 wired hooks classified policy vs behavioral (report-only) #2021)" — no gh/network access in this lane to fetch issue Hook-surface classification: 44 wired hooks classified policy vs behavioral (report-only) #2021; author-claimed, unverified.
• "markdownlint clean on edit" (PR body) — markdownlint-cli2 is not on PATH in this sandbox, so I could not re-run it myself; author-claimed, unverified. (.markdownlint-cli2.jsonc disables MD013 line-length, so the long paragraph lines in this section aren't a lint risk regardless.)
• The separate Codex review comment flagging that plugins/claude-config/skills/unhobble/SKILL.md doesn't yet support the hybrid class this rubric introduces — that's about a different file, out of scope for this docs-only PR's diff, and not something I re-verified independently, but worth tracking as a real follow-up gap between doctrine and the shipped tool that implements it.

Scope check (CLAUDE.md fresh-docs mandate)

Unchanged from the prior pass: this describes a classification methodology for existing hooks, not a hook-contract/manifest/harness-behavior change, so the fresh-docs citation requirement isn't triggered. No plugin manifests or contract-surface files are touched.

[kyle-sexton]

All three threads addressed. The two prose findings are fixed in f3409ed (finite-verb rewrite; the remediation sentence now names Evidence-gated additions explicitly and states the addition/removal symmetry). The codex P2 (unhobble's classification contract cannot represent a hybrid hook entry, so its strip plan contradicts trim-not-delete) is accepted and lands as its own small claude-config PR immediately after #2054 merges — the two would otherwise collide on the claude-config version from the same base (#1746 class). This PR stays docs-only.