apm pack --check-clean: rewrite error message to teach the amend+force-with-lease recipe

[danielmeppiel]

Problem

When apm pack --check-clean detects drift between the checked-in marketplace.json and what regeneration would produce, the error tells producers that there's drift but not how to fix it cleanly. Producers staring at a red CI status on their release PR end up doing one of:

• a noisy follow-up commit (chore: regen marketplace.json) that clutters the PR history
• a force-push without --force-with-lease, which is unsafe
• giving up and asking on the discussion forum (we've seen this twice: #1322, #1332)

The lockfile pattern (treat marketplace.json like package-lock.json — checked in, regenerated by pipeline, drift-gated in CI) is sound; what's missing is the teaching moment at the exact place the producer hits the wall.

Proposed fix

Rewrite the --check-clean error to include the canonical recovery recipe. Concretely, when drift is detected, emit:

[x] marketplace.json drift detected at .claude-plugin/marketplace.json

    Your checked-in marketplace.json doesn't match what 'apm pack' would
    generate from apm.yml. To recover cleanly:

      apm pack                       # regenerate locally
      git add .claude-plugin/marketplace.json
      git commit --amend --no-edit   # fold into the current commit
      git push --force-with-lease    # safe re-push

    Or as a follow-up commit:

      apm pack && git add .claude-plugin/marketplace.json
      git commit -m 'chore(marketplace): regen'

    Why this exists: marketplace.json is checked in (lockfile pattern)
    so consumers can resolve packages without running 'apm pack'. CI
    enforces that the checked-in copy matches the apm.yml source of
    truth.

Also: emit the same lines for each marketplace.outputs profile (claude, codex) so multi-output drift surfaces the right path per profile.

Out of scope (explicit)

• No pack-bot mode, no GitHub-App auto-regen, no pre-commit hooks. A DevUX panel evaluated those options (provocateur / pragmatist / automation lenses). The pragmatist verdict — ship the teaching error and re-evaluate later — won on "is the complexity worth it?". The lockfile pattern is fine; we just need to teach it at the right moment.
• No _generated_by JSON key change. Worth its own ticket if/when we see a real merge-conflict pain pattern in the wild.

Acceptance

• apm pack --check-clean on drift prints the recipe above (exact wording can iterate).
• The recipe handles multi-output (claude + codex) by listing the right path per profile.
• A test in tests/integration/ asserts the error text contains both commit --amend and force-with-lease.

Evidence trail

• Empirical surface: zava-agent-config v6.1.1 release (run 26079513903) where two community discussions traced back to this exact friction.
• Related but separate: apm-action#45 (v1.9.1) fixed the noisy 'produced N tarballs' warning seen in the same run; this issue is the remaining producer-side UX gap.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/marketplace
area/package-authoring
type/feature
status/accepted
priority/high

Milestone

null (0.15.0 not yet open; assign once the milestone is created)

Suggested next action

Implement the error message rewrite in the --check-clean drift handler, add the integration test asserting both commit --amend and force-with-lease appear in the output, and update the pack-distribute guide to document the recovery workflow.

Suggested issue comment

Thanks for the detailed write-up and for tracing this back to two concrete community discussions (#1322, #1332) -- that kind of empirical evidence makes the case clearly.

The "error as documentation" approach fits perfectly with how APM thinks about producer UX: the CLI should teach the recovery step at the exact moment you hit the wall, the same way npm teaches `npm audit fix` when an install warns you about vulnerabilities.

The proposed recipe covers the right cases:
- Amend path for single-commit release PRs (the common path)
- Follow-up commit path when amend is not viable
- `--force-with-lease` as the safe re-push gesture (vs. bare `--force`)
- Per-profile output paths for multi-output (claude + codex) drift

Acceptance criteria look good as written. One additional suggestion: the implementing PR should also update the pack-distribute guide ((microsoft.github.io/redacted) with a "Recovering from drift" section so the recipe is discoverable from docs as well as from the error output.

Marking `status/accepted` and `priority/high` -- the empirical friction evidence and the clear, bounded scope justify moving this to the next minor release queue.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user task is concrete: producers running apm pack --check-clean in CI hit a drift gate and have no recovery path in the error output. Two community discussions (#1322, #1332) empirically confirm the friction. The "error as documentation" pattern is strongly aligned with the npm/pip/cargo mental model APM commits to. The proposed text is actionable, specific, and correctly handles the multi-output (claude/codex) case. Acceptance criteria are well-scoped and map directly to the README's "Pack & distribute" capability.

Supply Chain Security Expert -- Risk-Surface Reviewer

The --check-clean flag guards marketplace.json lockfile-pattern integrity. This issue proposes only a UX change to the error message -- no change to drift-detection logic or integrity-check semantics. The --force-with-lease guidance in the recipe is safer than bare --force, a net positive. No theme/security or theme/governance surface implicated; this is a pure producer-side UX improvement. Primary theme: theme/portability -- enabling reliable, reproducible package distribution workflows.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is the project creator and COLLABORATOR with extensive prior interactions; standard maintainer-to-maintainer tone applies.

Python Architect -- Architecture Reviewer

Not activated -- the proposed change is an error message rewrite with a clear implementation path (modify the --check-clean drift error in the pack command handler and add an integration test); no interface, data model, or primitive design decision is required before code can land.

Doc Writer -- Documentation Reviewer

Activated. The implementing PR should update the pack-distribute guide to document the drift-recovery workflow, since the proposed error text is essentially an inline mini-guide. An area/docs-site secondary label would remind the PR author -- it was not added to keep the label set within the 6-label budget, but is surfaced here for the maintainer's consideration. Suggested comment wording is clear and grounded in the user vocabulary (apm pack, marketplace.json, lockfile pattern) used in the README and guides.

APM CEO -- Triage Arbiter

Accept. The request is empirically validated (two community discussions), well-specified, and scoped correctly -- no architecture work needed, just a targeted error-message improvement with a test. Aligns with APM's developer-experience-first positioning. Label set: theme/portability (primary), existing area/marketplace + area/package-authoring + type/feature preserved, status/accepted + priority/high added. Milestone set to null as 0.15.0 does not yet appear as an open milestone; the maintainer should assign once the milestone is created.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/marketplace", "area/package-authoring"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Implement the error message rewrite in the --check-clean drift handler, add the integration test asserting both 'commit --amend' and 'force-with-lease' appear in the output, and update the pack-distribute guide to document the recovery workflow.",
  "comment_markdown": "Thanks for the detailed write-up and for tracing this back to two concrete community discussions (#1322, #1332) -- that kind of empirical evidence makes the case clearly.\n\nThe \"error as documentation\" approach fits perfectly with how APM thinks about producer UX: the CLI should teach the recovery step at the exact moment you hit the wall, the same way npm teaches `npm audit fix` when an install warns you about vulnerabilities.\n\nThe proposed recipe covers the right cases:\n- Amend path for single-commit release PRs (the common path)\n- Follow-up commit path when amend is not viable\n- `--force-with-lease` as the safe re-push gesture (vs. bare `--force`)\n- Per-profile output paths for multi-output (claude + codex) drift\n\nAcceptance criteria look good as written. One additional suggestion: the implementing PR should also update the pack-distribute guide ((microsoft.github.io/redacted) with a 'Recovering from drift' section so the recipe is discoverable from docs as well as from the error output.\n\nMarking `status/accepted` and `priority/high` -- the empirical friction evidence and the clear, bounded scope justify moving this to the next minor release queue."
}

---

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.

Note

🔒 Integrity filter blocked 27 items

The following items were blocked because they don't meet the GitHub integrity level.

• #1120 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1122 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1130 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1138 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1156 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1157 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1209 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1225 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1231 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1266 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1273 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1293 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1295 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1300 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1326 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1329 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• ... and 11 more items

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Triage Panel · ● 632K · ◷