Feature: support lockfile-only resolution (`apm lock`)

[danielmeppiel]

Problem

apm install today is a single, all-or-nothing command: it resolves dependencies, writes apm.lock.yaml, and deploys files into target directories (.github/, .cursor/, .opencode/, etc.) in one shot. There is no mode that stops after the lockfile is written.

This blocks the declarative dotfiles workflow that users of Nix Home Manager, chezmoi, GNU Stow, yadm, and similar managers expect:

1. Edit apm.yml ("I want these packages")
2. Resolve + lock → write apm.lock.yaml
3. Commit only apm.yml + apm.lock.yaml to a dotfiles repo (no generated .github/ mirror)
4. On a new machine, activation (home-manager switch, chezmoi apply, etc.) calls apm install to deploy files into the right places from the pinned lockfile

Today step 3 is impossible without dirtying the working tree with deployed targets the user doesn't want under version control.

The npm analogue would be npm install --package-lock-only: resolve, write lockfile, touch nothing else.

Why

• Dotfiles users (chezmoi / Home Manager / Stow / yadm) version-control config and deploy on activation; they need lockfile-only commits.
• CI/CD pipelines that want a "resolve" step separated from a "deploy" step (e.g. a lockfile-update PR bot commits the new lockfile without running integrators).
• Monorepo maintainers who want to refresh lockfiles across workspaces without writing target files into every project tree.

The underlying principle is separating dependency resolution from deployment side effects — a fundamental composability property other package managers already provide.

Current behaviour

Mode	Writes lockfile?	Writes targets?
apm install --dry-run	No	No
apm install	Yes	Yes
apm install --lockfile-only (proposed)	Yes	No

There is no mode in the middle. --dry-run short-circuits before persisting anything (src/apm_cli/install/pipeline.py); regular install runs the integration phase unconditionally after the lockfile phase.

Proposed surface (open for discussion)

Two reasonable shapes — please flag preference:

A. Flag on apm install — apm install --lockfile-only

• Mirrors the npm install --package-lock-only mental model
• Skips integration phases when set
• Smallest surface area

B. Subcommand — apm lock

• Mirrors cargo generate-lockfile, pnpm lock
• Cleaner mental model for "I just want the lockfile"
• Could grow to apm lock --update, apm lock --check, etc.

Implementation either way is small: skip the integration phase when the new mode is active, keep the lockfile phase. Idempotency, exit codes, and --no-policy / --no-cache flags would behave identically to today's apm install.

Acceptance criteria

• Decide between --lockfile-only flag vs apm lock subcommand (UX call)
• Implement: skip integration phases when the mode is active
• apm.lock.yaml is written deterministically and matches what apm install would have produced
• No target files (.github/, .cursor/, .opencode/, etc.) are modified
• Existing --dry-run, --verbose, --no-policy, scope flags continue to work
• Test: install in lockfile-only mode, then run plain apm install from the same lockfile on a different machine and confirm parity
• Docs: Starlight cli-commands.md + apm-guide commands.md updated
• CHANGELOG entry under [Unreleased]

Use case from @ReoHakase (context)

Use case from dotfiles / Home Manager style setups: I want to commit only the APM manifest and lockfile, then let activation run user-scope install from that pinned state. Today there does not seem to be a lockfile-only command: --dry-run does not write apm.lock.yaml, and normal install writes targets.

— comment on #898

Related

• Spun off from Epic: Close the producer-produced drift-detection gap (per-asset lockfile + skill-as-package + apm audit --drift) #898 (drift detection) as a separate axis: install-time separation of concerns vs. post-install drift verification
• Adjacent: enhancement: apm install --root <dir> to target a directory other than $PWD #888 (--root <dir>) — controls where targets go; this issue controls whether targets are written at all. Composable.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/lockfile
area/cli
type/feature
status/accepted
priority/high

Milestone

0.9.4

Suggested next action

Resolve the apm install --lockfile-only vs apm lock subcommand UX question in a brief PR description note, then implement the mode gate in pipeline.py (skip integration phase after the lockfile phase) and update cli-commands.md + packages/apm-guide/.apm/skills/apm-usage/commands.md in the same PR.

Suggested issue comment

Thanks for the well-scoped write-up! This is accepted -- the separation of
lockfile resolution from file deployment is a genuine composability gap, and
the use cases (dotfiles managers, CI/CD "resolve then deploy" pipelines,
monorepo lockfile refresh) are all concrete.

**UX preference from triage:** `apm lock` subcommand (Option B) is the
stronger long-term shape. It mirrors `cargo generate-lockfile` / `pnpm lock`,
is discoverable from `apm --help` without knowing the flag name, and grows
naturally into `apm lock --update` / `apm lock --check` later. That said,
the final call is yours -- if `apm install --lockfile-only` maps better to
the existing surface, a flag is fine too.

**Implementation path** is straightforward: `src/apm_cli/install/pipeline.py`
already has a dry-run short-circuit before persistence; the new mode is
another gate after the lockfile phase and before integration dispatch. No
new architectural primitives needed.

**Acceptance criteria note:** the parity test (lockfile written in lockfile-only
mode == lockfile written by `apm install`) is the most important correctness
check -- it closes the drift/forgery vector identified in the related #898.

**Docs reminder:** the implementing PR must update both
`docs/src/content/docs/reference/cli-commands.md` and
`packages/apm-guide/.apm/skills/apm-usage/commands.md` per repo Rule 4,
plus a CHANGELOG entry under `[Unreleased]`.

Related:
- #898 (drift detection) -- this is the complementary "no-deploy" axis
- #888 (`--root <dir>`) -- controls where targets go; composable with this

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request maps to a real, concrete user task: committing apm.yml +
apm.lock.yaml to a dotfiles repo without dirtying the working tree with
deployed targets. The npm analogue (npm install --package-lock-only) is
direct and well-known. apm lock (Option B) is preferred over the flag
because it mirrors cargo/pnpm mental models, is discoverable from apm --help
independently, and creates a natural extension surface (apm lock --update,
apm lock --check). The acceptance criteria already covers flag composability,
exit codes, and CI behavior -- nothing is missing from the UX specification.

Supply Chain Security Expert -- Risk-Surface Reviewer

No new P/G/S risk surface introduced. Skipping the integration phase is
actually safer (fewer paths resolved, no file writes). The key
correctness-with-security-implications requirement is that the lockfile
produced in lockfile-only mode is byte-equivalent to what apm install would
produce -- a divergence would create a lockfile drift vector (#898 territory).
The acceptance criteria captures this parity requirement explicitly. Existing
theme/portability and area/lockfile labels are appropriate; no
theme/security addition is needed.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a core maintainer (COLLABORATOR + site_admin) with
deep project context; no tone-tuning or onboarding pointer adjustment is needed.

Python Architect -- Architecture Reviewer

Implementation is straightforward and the existing pipeline architecture
supports it. pipeline.py already has a dry-run short-circuit before
persistence; the new mode is a second short-circuit after the lockfile phase
and before integration dispatch. If apm lock subcommand is chosen, it is a
thin routing wrapper that calls the same pipeline with the new mode flag set.
No new interface, data model, or migration boundary is required.
status/needs-design is not warranted; status/accepted is correct. The only
subtle cross-cutting point is ensuring all existing flags (--no-policy,
--no-cache, --verbose, scope flags) compose correctly with the new mode --
the acceptance criteria already calls this out.

Doc Writer -- Documentation Reviewer

Docs work is clearly implied and explicitly called out in the acceptance
criteria (cli-commands.md + apm-guide/commands.md + CHANGELOG). An
area/docs-site secondary label would serve as a reminder, but the label
budget is at 6 and the requirement is already in the issue body, so it is not
added as a label. The implementing PR must update both the Starlight reference
page and the apm-guide skill resource per repo Rule 4. Comment wording is
clear, uses the correct vocabulary (apm.yml, apm.lock.yaml, integration
phase), and links to the related issues for context.

APM CEO -- Triage Arbiter

Accepted without reservation. This is a well-scoped feature request from a
core maintainer with multiple concrete use cases and a clear implementation
path. The apm lock subcommand (Option B) is the strategically stronger
choice -- it mirrors the cargo/pnpm positioning APM aspires to and creates a
composable surface for future lockfile management commands. Milestone 0.9.4
is appropriate given the small scope; priority/high is warranted given the
cited user demand (dotfiles community, CI/CD pipeline separation, monorepo
tooling). No specialist disagreements to arbitrate.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/lockfile", "area/cli"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": "0.9.4",
  "next_action": "Resolve the apm lock vs --lockfile-only UX question in the PR description, implement the mode gate in pipeline.py (skip integration phase after lockfile phase), and update cli-commands.md + apm-guide commands.md in the same PR.",
  "comment_markdown": "Thanks for the well-scoped write-up! This is accepted -- the separation of lockfile resolution from file deployment is a genuine composability gap, and the use cases (dotfiles managers, CI/CD resolve-then-deploy pipelines, monorepo lockfile refresh) are all concrete.\n\n**UX preference from triage:** `apm lock` subcommand (Option B) is the stronger long-term shape. It mirrors `cargo generate-lockfile` / `pnpm lock`, is discoverable from `apm --help` without knowing the flag name, and grows naturally into `apm lock --update` / `apm lock --check` later.\n\n**Implementation path** is straightforward: `src/apm_cli/install/pipeline.py` already has a dry-run short-circuit before persistence; the new mode is another gate after the lockfile phase and before integration dispatch.\n\n**Docs reminder:** the implementing PR must update both `docs/src/content/docs/reference/cli-commands.md` and `packages/apm-guide/.apm/skills/apm-usage/commands.md` per repo Rule 4, plus a CHANGELOG entry under `[Unreleased]`."
}

---

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 for issue #975 · ● 653.4K · ◷

[danielmeppiel]

Selected UX: ˋapm lock`