Repository navigation
docs: reground pages freed by #3918 and leftover 0.37 drift - #3982
Conversation
Refs #3948. Wave 2 of the 0.37 docs sweep (docs-corpus-audit): the pages #3918 owned (concepts, install-packages, enterprise policy and security, mcp-as-primitive, reference update/manifest-schema, apm-usage dependencies/governance) plus reference/cli/deps.md (#3916 refusal). Pages owned by in-flight #3290 are not touched. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
The docs overstate marketplace-free frozen replay and rebound-alias protection, omitting exceptions for missing package copies with locked MCP/LSP servers and lock rows without recorded origin evidence.
2 open issues
What changed in this PR
This documentation-only PR continues #3948’s APM 0.37 sweep, updating pages freed by #3918 and remaining reference drift. It aligns the docs site and bundled usage guidance with existing behavior without changing runtime code.
Changes:
- Corrects policy examples, enforcement scope, allow-list semantics, and quoted CLI output.
- Documents marketplace replay, refresh, origin checks, uninstall behavior, and newer-lockfile refusals.
- Updates target terminology, shared
.mcp.jsonguidance, and manifest validation details.
| File | Description |
|---|---|
packages/apm-guide/.apm/skills/apm-usage/governance.md |
Corrects policy semantics, enforcement scope, and diagnostics. |
packages/apm-guide/.apm/skills/apm-usage/dependencies.md |
Updates replay, refresh, selection pairing, and uninstall guidance. |
docs/src/content/docs/reference/manifest-schema.md |
Documents YAML-anchor rejection and marketplace replay. |
docs/src/content/docs/reference/cli/update.md |
Adds origin conflicts, newer-lockfile refusal, and proxy behavior. |
docs/src/content/docs/reference/cli/deps.md |
Documents newer-lockfile refusal for deprecated updates. |
docs/src/content/docs/producer/author-primitives/mcp-as-primitive.md |
Clarifies shared MCP configuration and placeholder handling. |
docs/src/content/docs/enterprise/security.md |
Updates marketplace-origin and host-policy guidance. |
docs/src/content/docs/enterprise/policy-reference.md |
Refreshes policy rules, discovery behavior, and outcome strings. |
docs/src/content/docs/enterprise/governance-guide.md |
Repairs policy examples and clarifies enforcement guarantees. |
docs/src/content/docs/enterprise/apm-policy.md |
Corrects transport, inheritance, and cache-refresh guidance. |
docs/src/content/docs/consumer/install-packages.md |
Adds default-host, replay, refresh, and compatibility guidance. |
docs/src/content/docs/concepts/primitives-and-targets.md |
Explains target aliases and shared project MCP configuration. |
docs/src/content/docs/concepts/lifecycle.md |
Clarifies target preservation during reinitialization. |
docs/src/content/docs/concepts/glossary.md |
Marks singular target and vscode terminology as deprecated. |
Review effort: Balanced
The new threat-model row credited #3895 with general dependency-confusion protection, but it only catches one install graph declaring the same owner/repo from two hosts; bare shorthand still resolves to the default host. The rebound sentence also omitted lock rows without a recorded origin, local marketplaces and in-repo moves, which the check skips. Addresses supply-chain-security-expert panel findings and Copilot inline on docs/src/content/docs/enterprise/security.md:323. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The apm-usage governance CLI samples used header and footer lines the CLI never prints and a dry-run overflow that cannot follow two lines (the preview limit is 5); align them with policy-reference. Section 3 still described a repo override in the discovered chain, and the allowlist rows said 'non-empty', contradicting null vs [] semantics. Addresses doc-writer and supply-chain-security-expert panel findings. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Locked marketplace entries replay offline except for a package whose locked MCP or LSP servers have no apm_modules copy; that case reads the marketplace even under --frozen (drift.py catalog-metadata). Also tie default_host to the shorthand rather than #ref and link the newer lockfile troubleshooting section. Addresses Copilot inline on reference/manifest-schema.md:701 and doc-writer panel nit on consumer/install-packages.md:64. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Doc Writer | 0 | 2 | 1 | Most added claims check out against source and all anchors resolve. Fix the skill dry-run block, the stale repo-override line and the default_host wording before merge. |
| Supply Chain Security Expert | 0 | 2 | 1 | Most policy claims match code. The dependency-confusion row overstates a layout-collision guard, and the alias-rebound claim omits unchecked cases. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 5 follow-ups
- [Supply Chain Security Expert] security.md: (a) Reword the Dependency confusion row so bare owner/repo is shown to always use the default host, recommend host/owner/repo plus host-qualified allow patterns, and describe fix(install): reject one owner/repo from two hosts before fetching (#3696) #3895 only as a same-graph two-host guard. (b) In the marketplace rebound sentence, say 'origin (its repository or marketplace.json URL)' and note that older lock rows without a recorded origin are not checked. -- Security admins rely on this table. As written it credits mitigations the code does not provide, which creates false assurance.
- [Doc Writer] apm-usage governance.md line 545: change the chain to 'enterprise hub -> org', and note that a repo apm-policy.yml applies only via apm audit --ci --policy. -- The skill now gives two contradicting answers about whether install enforces a repo-level policy file.
- [Supply Chain Security Expert] Replace 'non-empty dependencies.allow' with 'a set dependencies.allow ([] allows nothing)' in apm-usage governance.md (~778) and policy-reference.md (~135, ~1018). -- Leaving 'non-empty' suggests allow: [] means unrestricted, the opposite of what policy/matcher.py does.
- [Doc Writer] apm-usage governance.md dry-run example (~638): use the 5-line policy-reference form, the real 'Installing dependencies from apm.yml...' and 'Dry run mode - showing what would change:' headers, and drop the invented [i] lines. -- The example shows output the CLI cannot print, and agents copy it verbatim.
- [Doc Writer] install-packages.md ~64: attach the default_host clause to the owner/repo shorthand, not #ref, and link manifest-schema 3.15; link the troubleshooting section from the newer-lockfile bullet. -- A cheap fix for a misreading that suggests default_host affects ref resolution.
Copilot signals reviewed
- LEGIT
enterprise/security.md:323-- the rebound check skips lock rows withoutsource_url; matchescatalog_origin.py. Folded with follow-up 1. - LEGIT
reference/manifest-schema.md:701(+consumer/install-packages.md:181) --drift.pycatalog-metadata reads the marketplace for a package with locked servers and noapm_modules/copy, even under--frozen. Folded.
Recommendation
Fold all five follow-ups into this PR before landing. They are small text corrections in files the PR already touches, consistent with #3948's scope. The highest-signal item to confirm in the final diff is the security.md rewording. None of these needs a code change, so no deferred code findings come out of this panel.
Full per-persona findings
Doc Writer
- [recommended] The apm-usage governance.md dry-run example shows 2 preview lines and then '... and 4 more', which source cannot print. Two lines around it are also invented. at
packages/apm-guide/.apm/skills/apm-usage/governance.md:638
policy/install_preflight.py sets _DRY_RUN_PREVIEW_LIMIT = 5 and prints the overflow tail only after 5 lines, so 2 lines followed by '4 more' cannot happen. The lines '[i] Resolving dependencies...' and '[i] Dry-run: no files written' appear nowhere in src/apm_cli. Dry-run prints 'Dry run mode - showing what would change:' (install/presentation/dry_run.py:37) after 'Installing dependencies from apm.yml...' (core/command_logger.py:399). The PR edited lines 640-642 of this block, so the rest of it is in scope. Agents copy this skill output verbatim. policy-reference.md (around line 796) already has the correct 5-line form.
Suggested: Replace the block body with the policy-reference form. - [recommended] The new 'Repo-level: not auto-discovered' line contradicts section 3 of the same skill file, which still says 'enterprise hub -> org -> repo override'. at
packages/apm-guide/.apm/skills/apm-usage/governance.md:545
Line 10 now says a repo apm-policy.yml applies only when passed to apm audit --ci --policy. Section 3 (line 545) still says 'Policy resolves through the chain: enterprise hub -> org -> repo override.', which tells an agent that install also enforces a repo-level override. One skill file now gives two answers to the same question.
Suggested: Policy resolves through the chain: enterprise hub -> org, then the repo's apm.yml policy: stanza. A repo apm-policy.yml applies only via apm audit --ci --policy. - [nit] In install-packages.md the default_host clause attaches to #ref, so it reads as if the ref is resolved against default_host. The host applies to the owner/repo shorthand. at
docs/src/content/docs/consumer/install-packages.md:64
default_host selects the host for shorthand dependencies (manifest-schema.md section 3.15). It does not affect resolving tags, branches or commits. The new newer-lockfile bullet also does not link the troubleshooting section.
Suggested: Move the default_host clause onto the shorthand and link manifest-schema 3.15; link troubleshooting from the newer-lockfile bullet.
Supply Chain Security Expert
- [recommended] security.md threat table: the new Dependency confusion row claims more protection than the code gives. at
docs/src/content/docs/enterprise/security.md:635
The mitigation is fix(install): reject one owner/repo from two hosts before fetching (#3696) #3895, which only catches a host-blind apm_modules layout collision when one install graph declares the same owner/repo from two hosts. A single bare owner/repo still resolves to the default host (GITHUB_HOST, else github.com) with no check, and that is the classic confusion vector. The *.ghe.com half is accurate.
Suggested: Reword the threat to 'Bare owner/repo resolves on an unintended host' and state that bare shorthand always uses the default host; recommend host/owner/repo plus host-qualified allow patterns. - [recommended] security.md: the marketplace rebound sentence over-promises with 'points somewhere else'. at
docs/src/content/docs/enterprise/security.md:323
require_locked_catalog_origin compares only the recorded source_url and accepts lock rows without one; a catalog moved within the same repository is not detected; origins also cover hosted marketplace.json URLs, so 'Git origin' is too narrow.
Suggested: Say 'origin (its repository or marketplace.json URL)' and note older rows without an origin are not checked. - [nit] The allowlist violation-class rows still say 'non-empty', which contradicts the null vs [] semantics this PR adds. at
packages/apm-guide/.apm/skills/apm-usage/governance.md:778
policy/matcher.py _resolve_allow_deny returns no opinion for None and blocks everything for (). 'non-empty dependencies.allow' suggests allow: [] means no restriction.
Suggested: Replace 'non-empty dependencies.allow' with 'a set dependencies.allow ([] allows nothing)' here and in policy-reference.md lines 135 and 1018.
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.
security.md no longer says policy patterns are host-blind or cannot restrict host identity: dependencies.allow/deny accept host-qualified patterns (policy-reference). The docs-contract test still pinned the old wording and failed Build & Test Shard 1. Keep its intent (no transport-aware policy claim) and assert the scheme-blind sentence and the host-qualified link instead. Addresses CI failure in tests/unit/test_tls_docs_scope.py:127. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Each parsed manifest, transitive ones included, resolves its own bare owner/repo dependencies against its own default_host, so a root default_host does not pin the whole graph. Say so in the dependency-confusion row and point at host-qualified allow patterns as the control. Addresses supply-chain-security-expert delta panel finding on docs/src/content/docs/enterprise/security.md:635. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Doc Writer | 0 | 0 | 0 | All 3 prior findings are fixed correctly. New claims match the source, links and anchors resolve, and apm-usage skill files are ASCII-only. No new findings. |
| Supply Chain Security Expert | 0 | 1 | 0 | All 3 prior findings fixed. The host precedence, origin-rebound limits and test intent match the code. One wording gap: the default_host that applies belongs to the manifest that declares the dependency. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Folded in this run
- security.md dependency-confusion row scoped to code (fix(install): reject one owner/repo from two hosts before fetching (#3696) #3895 same-graph two-host guard; bare shorthand uses the declaring manifest's default host; host-qualified allow patterns) -- 15d003a, 43a76be
- security.md rebound sentence: origin = repository or
marketplace.jsonURL; rows without an origin, local marketplaces and in-repo moves not checked -- 15d003a - apm-usage governance: CLI samples match real output (dry-run 5-line cap), repo policy not in the discovered chain, allow-list
[]wording (also policy-reference) -- 4fc0295 - Marketplace replay exception for locked MCP/LSP servers without an
apm_modules/copy; default_host tied to shorthand; troubleshooting link -- 0dd1ac2 - Docs-contract test
tests/unit/test_tls_docs_scope.pytracks the host-qualified wording (CI fix) -- f4854f3
Copilot signals reviewed
- LEGIT
enterprise/security.md:323rebound check skips rows withoutsource_url-- folded 15d003a, thread resolved. - LEGIT
reference/manifest-schema.md:701frozen replay reads the marketplace for locked servers without anapm_modules/copy -- folded 0dd1ac2, thread resolved.
Evidence
- Lint:
ruff check src/ tests/andruff format --check src/ tests/silent; apm-usage files 0 non-ASCII bytes. - CI: all checks green on
43a76be(26 success, 2 neutral, 1 skipped).
| PR | Head | Stance | Iterations | Folds | Deferrals | Copilot rounds | CI | Mergeable | Merge state | Notes |
|---|---|---|---|---|---|---|---|---|---|---|
| #3982 | 43a76be | ship_now | 2 | 9 | 0 | 2 | green | MERGEABLE | BLOCKED | pending required review |
Recommendation
Ready to land with CI green on the 43a76be head. Nothing is left to track from this panel. Issue #3948's scope for these pages is met, and no code findings were deferred.
Full per-persona findings
Doc Writer
No findings.
Supply Chain Security Expert
- [recommended] security.md Dependency confusion row: name the manifest whose default_host applies, so readers do not think a root default_host pins transitive bare deps. at
docs/src/content/docs/enterprise/security.md:635
APMPackage.from_apm_yml (models/apm_package.py:719) enters manifest_host_scope_for(data) for each parsed manifest, including transitive packages (deps/apm_resolver.py:1701). So a dependency's own default_host decides where its bare owner/repo deps resolve, not the root's. The host-qualified allow-pattern advice in the same cell is the real control.
Suggested: Bare shorthand uses the declaring manifest's default host (its default_host, else GITHUB_HOST, else github.com); enforce hosts with host-qualified allow patterns.
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.

Description
TL;DR — Wave 2 of the 0.37 docs sweep. It covers the pages owned by #3918, which has now landed, and one leftover from #3949's review (
reference/cli/deps.md). The edits are surgical and checked againstmainatee00d6aaeb. The approval wording #3918 wrote is unchanged; this PR fixes only the drift around it.Problem (WHY)
apm-usage/governance.mdwas the most stale page. Its schema showedallow: []while the text said an empty list permits all; in code,nullmeans no opinion and[]allows nothing. It also namedtrust_transitiveas enforced and as a remedy when it is not. It used the deprecatedapm deps update, and its CLI output samples no longer matched the real strings.extends: "enterprise-hub-org"(a bare org is not a policy repo),compilation.target.enforce: true, the non-existentapm install --no-cache, andpolicy: enforcement:inapm.yml, which the project config does not read.apm-usage/dependencies.md,consumer/install-packages.mdand the concepts pages still showedapm install --update, singulartarget:and the pre-feat(deps): exact per-edge skills x targets pairing for diamonds (req-rs-018) #3769 diamond union. They omitted thevscodealias, theintellijrefusal, root.mcp.jsonshared with Claude Code, lock-first marketplace replay (fix(install): replay locked marketplace dependencies from the lockfile #3915), revalidation (fix(marketplace): explicit refresh revalidates catalogs or fails (#3279) #3910) and object-form uninstall (fix(uninstall): remove object-form marketplace entries by plugin@marketplace #3933).reference/cli/{update,deps}.mdandmanifest-schema.mdwere missing the fix(lockfile): refuse lockfiles written by a newer APM (#2334) #3916 and fix(marketplace): record catalog origin in the lock; fail closed on rebound aliases #3917 failures, the YAML-anchor refusal (fix(manifest): route init re-init target rewrites through the declaration owner; reject apm.yml YAML anchors #3867) and locked marketplace replay.Approach / Implementation
enterprise/{apm-policy,governance-guide,policy-reference,security}.mdfetch_failurestricter-wins rowapm-usage/governance.mdapm updateapm-usage/dependencies.md,consumer/install-packages.md--updatemarked deprecated; per-declaration diamond pairing; replay, revalidation, object-form uninstall and newer-lockfile notes;default_hostconcepts/{glossary,lifecycle,primitives-and-targets}.md,producer/author-primitives/mcp-as-primitive.mdtargets:/vscodealias /intellij; root.mcp.jsonshared with Claude Code (which ignores Copilottools);apm initre-init behaviour (#3867)reference/cli/{update,deps}.md,reference/manifest-schema.mdPROXY_REGISTRY_ONLYwithapm update, YAML anchors, locked marketplace replayTrade-offs
installing-from-marketplaces,hooks-and-commands,reference/cli/{install,uninstall},package-types,specs/openapm-v0.1andapm-usage/commands.md.Issue and approved scope
Issue: Refs #3948
Human scope-approval comment: #3948 (comment)
Does this PR complete the issue, or what remains? Partial. The drift that #3290 leaves on its pages remains and will be re-checked once #3290 lands.
Type of change
Testing
Validation evidence
apm <verb> --help, asrc/apm_cligrep, or a direct classifier run (for example,classify_unbounded_reasonreturnsBARE_BRANCHforv01.2.3).apm-usagefiles contain 0 non-ASCII bytes.Changelog
Spec conformance (OpenAPM v0.1)
How to test
apm-usage/governance.mdschema showsallow: nullwith "[] = allow nothing" (seepolicy/matcher.py_resolve_allow_deny)reference/cli/update.mdnames the rebound-alias failure; compare withmarketplace/errors.pyMarketplaceOriginConflictErrorCo-authored-by: Copilot 223556219+Copilot@users.noreply.github.com