Skip to content

docs: reground pages freed by #3918 and leftover 0.37 drift - #3982

Merged
Daniel Meppiel (danielmeppiel) merged 7 commits into
mainfrom
danielmeppiel-docs-037-followup
Nov 19, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 7 commits into
mainfrom
danielmeppiel-docs-037-followup

Conversation

@danielmeppiel

Copy link
Copy Markdown
Collaborator

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 against main at ee00d6aaeb. The approval wording #3918 wrote is unchanged; this PR fixes only the drift around it.

Problem (WHY)

Approach / Implementation

Area Change
enterprise/{apm-policy,governance-guide,policy-reference,security}.md Correct examples and outcome strings; adds #3788, #3894, #3783, #3916, #3917 and #3895/#3923, plus a fetch_failure stricter-wins row
apm-usage/governance.md Allow-list semantics, install vs audit enforcement split, real CLI strings, apm update
apm-usage/dependencies.md, consumer/install-packages.md --update marked deprecated; per-declaration diamond pairing; replay, revalidation, object-form uninstall and newer-lockfile notes; default_host
concepts/{glossary,lifecycle,primitives-and-targets}.md, producer/author-primitives/mcp-as-primitive.md targets: / vscode alias / intellij; root .mcp.json shared with Claude Code (which ignores Copilot tools); apm init re-init behaviour (#3867)
reference/cli/{update,deps}.md, reference/manifest-schema.md #3916 refusal, #3917 rebound alias, PROXY_REGISTRY_ONLY with apm update, YAML anchors, locked marketplace replay

Trade-offs

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

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally
  • All existing tests pass
  • Added tests for new functionality (if applicable)
Validation evidence
  • Claims were checked per page with apm <verb> --help, a src/apm_cli grep, or a direct classifier run (for example, classify_unbounded_reason returns BARE_BRANCH for v01.2.3).
  • Every added relative link and anchor resolves.
  • apm-usage files contain 0 non-ASCII bytes.
  • No Python changes.

Changelog

  • N/A -- docs only; the behaviour already has CHANGELOG entries.

Spec conformance (OpenAPM v0.1)

  • N/A -- this PR does not change OpenAPM-observable behaviour.

How to test

  • apm-usage/governance.md schema shows allow: null with "[] = allow nothing" (see policy/matcher.py _resolve_allow_deny)
  • reference/cli/update.md names the rebound-alias failure; compare with marketplace/errors.py MarketplaceOriginConflictError

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

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>
Copilot AI balanced review requested due to automatic review settings November 19, 2026 19:19
@danielmeppiel Daniel Meppiel (danielmeppiel) added this to the 0.37.0 milestone Nov 19, 2026
@danielmeppiel Daniel Meppiel (danielmeppiel) added the type/docs Documentation change (prose, examples, generated reference). label Nov 19, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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.json guidance, 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>
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

APM Review Panel: ship_with_followups

Docs sweep regrounds 14 pages and the apm-usage skill against 0.37 main. Two security.md lines claim more protection than the code provides, so fix them before landing.

panel-mode=full; personas=doc-writer,supply-chain-security-expert(adhoc),apm-ceo

cc Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

Both panelists agree the PR does what issue #3948 asked for: surgical edits, anchors that resolve, and no README or #3290-owned pages touched. Neither returned a blocking finding, neither attached test evidence, and they did not disagree. The six findings are all docs-truthfulness corrections inside the PR's own files. None reopens scope, and none needs a code change. So the question is not whether this lands, but which corrections matter most before it does.

The security corrections come first. The enterprise security page is the document a security admin pastes into a risk review. The new Dependency confusion row credits #3895 with a mitigation it does not provide. #3895 only catches an install graph that declares the same owner/repo from two hosts. A bare owner/repo still resolves silently to the default host, and that is the classic confusion vector. The marketplace rebound sentence says APM detects an origin that 'points somewhere else'. In fact the check compares only the recorded source_url, skips lock rows that have no origin, and cannot see a catalog that moved within the same repository. Claiming protection we do not have costs more trust than leaving the row out. Scope each claim down to exactly what the code enforces, and point admins to host-qualified dependencies and allow patterns.

The governance skill needs to agree with itself. packages/apm-guide ships the skill that agents read and repeat word for word. One file now says a repo apm-policy.yml applies only through audit --ci --policy, while section 3 still describes a repo override in the resolution chain. The dry-run example contains output the CLI cannot produce: overflow text after 2 lines when the preview limit is 5, plus two invented [i] lines. The 'non-empty dependencies.allow' wording contradicts the null-vs-[] semantics this PR itself adds. The default_host wording is a real but low-signal nit, so fold it because it is cheap.

Aligned with: secure by default -- The threat table and rebound sentence must describe only what the code enforces. Bare owner/repo goes to the default host without a check, and that limit should be stated plainly. governed by policy -- The PR's null-vs-[] allowlist semantics and the repo-policy scope are correct, but the skill and policy-reference still have contradicting lines. Fix them so admins and agents get one answer. multi harness multi host -- Tie default_host to the owner/repo shorthand, not to #ref resolution. pragmatic as npm -- Quoted CLI output in the skill must be text the CLI can actually print.

Panel summary

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

  1. [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.
  2. [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.
  3. [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.
  4. [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.
  5. [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 without source_url; matches catalog_origin.py. Folded with follow-up 1.
  • LEGIT reference/manifest-schema.md:701 (+ consumer/install-packages.md:181) -- drift.py catalog-metadata reads the marketplace for a package with locked servers and no apm_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>
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

APM Review Panel: ship_now

Delta review: all five iteration-1 follow-ups, both Copilot items, and the one new delta finding are folded. The 0.37 docs sweep is now accurate on security, governance, and marketplace replay.

panel-mode=delta; personas=doc-writer,supply-chain-security-expert,apm-ceo

cc Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

Since the last advisory (cf26034), five commits landed. 15d003a rewrote the security.md dependency-confusion row and rebound sentence. 4fc0295 fixed the governance skill CLI samples, the repo-policy chain, and the allow-list wording. 0dd1ac2 added the frozen marketplace replay exception and corrected the default_host wording. f4854f3 updated tests/unit/test_tls_docs_scope.py to the host-qualified wording and kept the no-transport-aware-policy intent. 43a76be names the declaring manifest whose default_host applies. Main merged in without conflicts. Both delta panelists confirmed every prior finding is fixed. doc-writer returned no new findings. supply-chain-security-expert raised one recommended wording gap: a transitive dependency's own default_host decides where its bare deps resolve (models/apm_package.py:719, deps/apm_resolver.py:1701). That gap is now folded with the suggested wording.

The panelists did not disagree. The security table now claims only what the code enforces. Bare shorthand is tied to the declaring manifest's host, #3895 is scoped to the same-graph two-host guard, and host-qualified allow patterns are named as the real control. That was the trust risk flagged in iteration 1, and it is closed. No follow-ups remain.

Aligned with: secure by default -- The dependency-confusion and rebound rows now state exactly what the code enforces, including the per-manifest default_host scope and lock rows without a source_url. governed by policy -- The skill and policy-reference now agree on null-vs-[] allow semantics and on the repo-policy scope (apm audit --ci --policy only). multi harness multi host -- default_host is tied to owner/repo shorthand and scoped to the declaring manifest, matching resolver behavior. pragmatic as npm -- Quoted CLI output in the governance skill now matches what the CLI actually prints.

Panel summary

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.json URL; 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.py tracks the host-qualified wording (CI fix) -- f4854f3

Copilot signals reviewed

  • LEGIT enterprise/security.md:323 rebound check skips rows without source_url -- folded 15d003a, thread resolved.
  • LEGIT reference/manifest-schema.md:701 frozen replay reads the marketplace for locked servers without an apm_modules/ copy -- folded 0dd1ac2, thread resolved.

Evidence

  • Lint: ruff check src/ tests/ and ruff 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.

@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit 0a0f2a2 into main Nov 19, 2026
29 checks passed
@danielmeppiel
Daniel Meppiel (danielmeppiel) deleted the danielmeppiel-docs-037-followup branch November 19, 2026 20:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type/docs Documentation change (prose, examples, generated reference).

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants