Plugin bin/ deploy: trust-posture, producer docs, and hardening follow-ups (from #1591 review panel)

[danielmeppiel]

Tracks the deferred, improvement-tier follow-ups surfaced by the advisory review panel on #1591 (marketplace_plugin bin/ deployment to ~/.claude/skills/<name>/). None blocked #1591; the highest-signal findings were folded there (manifest symlink guard, governance.md Rule-4 drift, native-skill+bin/ and symlink-rejection regression tests, doc wording). This issue collects the rest.

1. Trust posture: opt-in / first-deploy consent (security + DevX)

Both supply-chain-security and devx-ux flagged that default-on bin/ deployment places package executables on Claude Code's PATH without explicit consent. v1 ships with the bin_deploy deny / deny_all policy escape hatch and matches npm's bin-link mental model, so this is a v2 design call, not a regression.

• Consider an opt-in flag (--deploy-bin) or a prominent first-deploy warning on the first install of any new plugin that ships bin/.
• Surfaces: src/apm_cli/integration/skill_integrator.py (_deploy_plugin_bin).

2. Producer-facing "publishing plugins with binaries" guide (growth + docs)

The feature is currently documented only on the admin opt-out surface (policy-schema.md + apm-usage/governance.md). A plugin author has no entry point describing the 3-step path (add bin/, ensure marketplace_plugin package type, publish).

• Add a short producer/authoring guide page and cross-link it from the bin_deploy policy section.
• Story angle for the next minor: "Ship your CLI as an APM plugin -- Claude invokes it like a native command."

3. Least-privilege hardening (security)

• Tighten the deployed-executable mode from group+other execute toward user-only execute (0o700-style), given the ~/.claude/skills/ user-scope constraint. Land before any future system-scope expansion.
• Normalize bin_deploy.deny matching (case / host-prefix) or document that entries must be lowercase canonical owner/name.
• Surfaces: _copy_plugin_file (~chmod), _bin_deploy_denied (deny match).

4. Project-scope silent no-op hint (DevX)

A marketplace_plugin that ships bin/ installed at project scope silently does not deploy executables. Emit a visible hint to re-run with -g.

• Surface: src/apm_cli/integration/skill_integrator.py (project-scope skip path).

5. _merge_bin_paths value-object hygiene (architecture)

_merge_bin_paths mutates a non-frozen SkillIntegrationResult in place yet also returns it (modify-then-return). Prefer dataclasses.replace() for a pure value-object pattern, matching policy/schema.py. Prevents future bugs if the result is ever frozen or shared across threads.

6. (Deferred architecture) TargetProfile plugin-bin contract

The Claude-specific gate (target.name == "claude") is honest single-consumer v1 code. If/when a second harness ships the same skills-directory-plugin contract, extract a TargetPluginBinContract protocol and move the harness-specific logic behind it.

---

Source: advisory review panel on #1591 (python-architect, cli-logging-expert, devx-ux-expert, supply-chain-security-expert, oss-growth-hacker, doc-writer, test-coverage-expert; apm-ceo synthesis stance ship_with_followups).

[danielmeppiel]

Update: per maintainer request, the recommended-severity panel items have now been folded into PR #1591 (commit 21a20ee1) rather than deferred here:

• python-architect: _merge_bin_paths made pure via dataclasses.replace().
• devx-ux: project-scope skip now surfaces a structured bin_skipped_reason -> install prints an actionable -g hint (no more silent no-op).
• cli-logging/devx: deploy line reworded ('Claude Code', split reload instruction, 'invoked without confirmation').
• supply-chain/devx: trust-posture warning surfaced inline at deploy time.
• doc-writer: producer-facing bin/ authoring guidance (repo-shapes.md + package-authoring.md), cross-linked from policy-schema.md.

Still deferred to this issue (out of scope for the recommended fold): the full opt-in/consent trust redesign (opt-out -> opt-in), chmod 700 hardening, deny-list normalization, and the TargetProfile plugin-bin-contract abstraction.

[github-actions]

Triage decision

accept

Proposed labels

theme/security
area/marketplace
area/cli
area/docs-site
type/feature
status/accepted
priority/low

Milestone

null

Suggested next action

Pick up items 1-5 as incremental implementation tasks; open a separate design issue for item 6 (TargetProfile plugin-bin contract) before any harness-abstraction code lands.

Suggested issue comment

Thanks for the structured follow-up tracking. The panel reviewed all six items and finds them well-scoped and aligned with the APM plugin authoring story.

Items 1-5 are accepted for implementation: the trust-posture consent mechanism (item 1), the producer authoring guide (item 2), least-privilege chmod hardening and deny-list normalization (item 3), the project-scope hint for non-global installs (item 4), and the `_merge_bin_paths` value-object refactor (item 5) are each bounded, low-risk improvements that strengthen the `bin/` deployment story without breaking existing behavior.

Item 6 (TargetProfile plugin-bin contract) is conceptually sound but requires a design step before code lands safely. The protocol interface, the migration boundary for the Claude-specific gate, and the harness discovery mechanism must be settled first. A separate issue with `status/needs-design` would be the right place to track it.

One note: only a 0.14.0 milestone is currently open in the repo, but the project is at 0.16.x -- so no milestone is assigned here. Please assign the appropriate current patch or minor milestone when scheduling.

Next step: if you have a preferred sequencing for items 1-5, annotate the checklist and open draft PRs one item at a time so the review panel can stay focused.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

All six items map to real user surfaces. Item 1 closes the npm-mental-model gap (bin-linking should require explicit opt-in). Item 4 closes a silent-failure case that violates the package manager contract of "tell the user when a scoped operation is silently skipped." Items 2 and 3 are standard hardening for the plugin authoring story. All items are grounded in existing APM capabilities and add no new conceptual surface.

Supply Chain Security Expert -- Risk-Surface Reviewer

Items 1 and 3 are directly on the supply-chain trust surface: default-on bin deployment without consent places package-supplied executables on Claude Code's PATH, and group+other execute permissions widen the attack surface beyond user scope. The deny-list normalization (case/host-prefix) is governance-adjacent -- inconsistent matching could allow bypass. theme/security and area/marketplace are required. area/cli covers items 4 and 5; area/docs-site covers item 2.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- danielmeppiel is a collaborator with established context; standard technical tone is appropriate.

Python Architect -- Architecture Reviewer

Items 1-5 are bounded changes within existing modules. Item 5 (_merge_bin_paths value-object refactor) is a clean improvement aligned with the dataclasses.replace() pattern used elsewhere in the codebase. Item 6, however, requires a design decision: the TargetPluginBinContract protocol shape, its discovery mechanism, and how the Claude-specific target.name == "claude" gate migrates must be settled before code lands. A separate design issue is recommended for item 6.

Doc Writer -- Documentation Reviewer

Item 2 explicitly requires a new producer/authoring guide page for the bin/ deployment story. area/docs-site should ride as a secondary label on this issue so the implementing PR is reminded to include the docs work. Vocabulary to use: "plugin authoring", "binary deployment", "bin/ directory" -- consistent with the README and marketplace docs.

APM CEO -- Triage Arbiter

Well-formed follow-up from a collaborator. The existing status/accepted is correct. Items 1-5 proceed to implementation; item 6 should be spun off as a separate design issue. theme/security reflects the supply-chain trust gap in item 1 and the hardening in item 3. priority/low is appropriate since the deny/deny_all policy escape hatch provides adequate protection for v1.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/security",
  "areas": ["area/marketplace", "area/cli", "area/docs-site"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Pick up items 1-5 as incremental implementation tasks; open a separate design issue for item 6 before any harness-abstraction code lands.",
  "comment_markdown": "Thanks for the structured follow-up tracking. The panel reviewed all six items and finds them well-scoped and aligned with the APM plugin authoring story."
}

---

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 · sonnet46 3.8M · ◷