feat(compile): add --no-dedup / --force-instructions flag for claude target

[sergio-sisternes-epam]

Context

PR #1146 introduced deduplication logic for apm compile --target claude: when .claude/rules/ already contains per-instruction files, the compiler omits the instructions section from CLAUDE.md to avoid duplicate context.

Request

Add an escape hatch flag (--no-dedup or --force-instructions) on apm compile --target claude so users can opt out of the deduplication behaviour when needed (e.g. debugging, or when the user intentionally wants both copies).

Source

Recommended by the devx-ux-expert persona during the apm-review-panel pass on PR #1146.

Acceptance criteria

• New CLI flag accepted by apm compile
• When set, instructions section is always included in CLAUDE.md regardless of .claude/rules/ contents
• Unit test covering the flag
• Docs updated in docs/src/content/docs/producer/compile.md

[github-actions]

Triage decision

accept

Proposed labels

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

Milestone

0.14.0

Suggested next action

Implement --force-instructions on apm compile for the claude target, add a unit test, and update docs/src/content/docs/producer/compile.md to document the flag.

Suggested issue comment

Thanks for filing this! PR #1146's deduplication logic was a sensible default -- omitting the instructions section from CLAUDE.md when .claude/rules/ already contains per-instruction files avoids duplicate context in the normal flow. But the absence of an opt-out is a real gap for users who need both copies (debugging workflows, tooling setups that consume both surfaces independently).

`--force-instructions` reads clearly to someone who knows `apm compile --target claude`: it says "always include the instructions section regardless of what is already in .claude/rules/". That is the preferred flag name over `--no-dedup`, which refers to an internal mechanism the user does not need to know about.

The acceptance criteria as written (flag, unit test, docs) is exactly right. To move forward:

1. Open a PR that adds `--force-instructions` to `apm compile` under the claude target path.
2. Add a unit test covering the flag (the AC lists this explicitly -- please include it in the same PR).
3. Update `docs/src/content/docs/producer/compile.md` to document the new flag with a short example.

Relevant reference: https://github.com/microsoft/apm/blob/main/docs/src/content/docs/producer/compile.md

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request maps to a real user surface: apm compile --target claude introduced deduplication in PR #1146 with no opt-out. Use cases (debugging context duplication, tooling setups that consume both CLAUDE.md and .claude/rules/ independently) are concrete and legitimate. The escape hatch pattern is familiar from npm/pip (--no-cache-dir, --force, --no-save). --force-instructions is preferred over --no-dedup because it positively names the effect rather than negating an internal mechanism. Acceptance criteria (flag, unit test, docs) is already well-structured. Discoverability is fine via apm compile --help.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. apm compile --target claude generates context config files (CLAUDE.md, .claude/rules/), not packages, lockfiles, or auth artifacts. Adding an opt-out flag for deduplication touches none of the P/G/S threat surfaces (no dependency resolution, no lockfile, no signing, no download path, no token handling). theme/security and theme/governance are not required.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a COLLABORATOR with established project familiarity; standard professional tone is appropriate and the issue does not signal a new or low-interaction contributor.

Python Architect -- Architecture Reviewer

Not activated -- the feature is well-scoped to a single flag in the claude target compiler path with explicit acceptance criteria; no cross-module interface, data model, or migration boundary decision is required before code can land safely.

Doc Writer -- Documentation Reviewer

Docs work is explicitly required in the acceptance criteria ("Docs updated in docs/src/content/docs/producer/compile.md"). area/docs-site rides as a secondary area/* label to ensure the implementing PR is reminded to include the doc update. The suggested comment wording points directly to the compile doc URL so the author has a concrete reference.

APM CEO -- Triage Arbiter

Accept. This is a small, well-defined escape hatch originating from a devx-ux-expert recommendation during the apm-review-panel pass on PR #1146 -- a credible, in-project source with clear rationale. The feature expands compile target flexibility (theme/portability), carries zero security or governance footprint, and arrives with a complete acceptance checklist. Assign to 0.14.0 (the only currently open milestone) as a low-priority item; the flag is narrow enough that it should not block the milestone but is ready to be picked up.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/cli", "area/docs-site"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": [],
  "milestone": "0.14.0",
  "next_action": "Implement --force-instructions on apm compile for the claude target, add a unit test, and update docs/src/content/docs/producer/compile.md to document the flag.",
  "comment_markdown": "Thanks for filing this! PR #1146's deduplication logic was a sensible default -- omitting the instructions section from CLAUDE.md when .claude/rules/ already contains per-instruction files avoids duplicate context in the normal flow. But the absence of an opt-out is a real gap for users who need both copies (debugging workflows, tooling setups that consume both surfaces independently).\n\n`--force-instructions` reads clearly to someone who knows `apm compile --target claude`: it says \"always include the instructions section regardless of what is already in .claude/rules/\". That is the preferred flag name over `--no-dedup`, which refers to an internal mechanism the user does not need to know about.\n\nThe acceptance criteria as written (flag, unit test, docs) is exactly right. To move forward:\n\n1. Open a PR that adds `--force-instructions` to `apm compile` under the claude target path.\n2. Add a unit test covering the flag (the AC lists this explicitly -- please include it in the same PR).\n3. Update `docs/src/content/docs/producer/compile.md` to document the new flag with a short example.\n\nRelevant reference: https://github.com/microsoft/apm/blob/main/docs/src/content/docs/producer/compile.md"
}

---

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 20 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".
• #1273 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".
• #1341 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1342 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1343 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• ... and 4 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 · ● 519K · ◷