[docs] Update documentation for features from 2026-04-25

[danielmeppiel]

Documentation Updates - 2026-04-25

This PR updates the documentation based on features merged in the last 24 hours.

Features Documented

• Bug fix: policy cache path resolution on Windows (from Windows: _get_cache_dir flakes on tmpdir 8.3 short names (PathTraversalError) #886, fix(policy): resolve project_root before path-traversal check #895)

Changes Made

• Updated CHANGELOG.md to add the missing ### Fixed entry for PR Windows: _get_cache_dir flakes on tmpdir 8.3 short names (PathTraversalError) #886 (cherry-picked as fix(policy): resolve project_root before path-traversal check #895): discover_policy now resolves project_root to its canonical long-name form before computing the cache path, preventing 8.3 short-name/long-name mismatches from triggering a false PathTraversalError on Windows.

Merged PRs Referenced

• fix(policy): resolve project_root before path-traversal check #895 - fix(policy): resolve project_root before path-traversal check

Notes

The only code change merged in the last 24 hours was the cherry-pick of #886 as #895. The fix itself (a one-line project_root = project_root.resolve() in src/apm_cli/policy/discovery.py) was already present in the codebase, but the corresponding CHANGELOG.md entry was missing from the [Unreleased] section. No other documentation files required changes as this is an internal bug fix with no user-facing API or command surface changes.

Generated by Daily Documentation Updater · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/daily-doc-updater.md@b87234850bf9664d198f28a02df0f937d0447295

• expires on Apr 27, 2026, 3:45 AM UTC

[Copilot]

Pull request overview

Updates the project changelog to document a recently merged Windows policy-cache bug fix (PRs #886 and #895) that was missing from the [Unreleased] section.

Changes:

• Add a [Unreleased] -> Fixed changelog entry describing the Windows policy cache path normalization fix.

Show a summary per file

File	Description
CHANGELOG.md	Adds a new bullet under [Unreleased] documenting the Windows policy cache path resolution fix.

Copilot's findings

• Files reviewed: 1/1 changed files
• Comments generated: 2

[Copilot]

Under ## [Unreleased], ### Fixed appears twice (once at line 30 and again at line 40), which breaks the Keep a Changelog structure and makes entries easy to miss. Please consolidate into a single ### Fixed section and place this new bullet under that single section (also worth double-checking the rest of the file for any merge artifacts).

See below for a potential fix:

- `apm update` sanitises the subprocess environment before invoking the platform installer so the bundled PyInstaller `LD_LIBRARY_PATH` / `DYLD_*` no longer leak into system binaries (`curl`, `tar`, `sudo`) spawned by `install.sh`. Previously the installer's first `curl` call could abort with `libssl.so.3: version 'OPENSSL_3.2.0' not found` on distros whose system `libcurl` requires a newer OpenSSL ABI than the APM bundle ships (Debian trixie arm64 dev-containers, Fedora 43, and similar). Restoration uses PyInstaller's official `<VAR>_ORIG` protocol, preserving the user's own `LD_LIBRARY_PATH` exports. Closes #894
- Policy cache path resolution on Windows: `discover_policy` now resolves `project_root` to its canonical long-name form before computing the cache path, preventing 8.3 short-name/long-name mismatches from triggering a false `PathTraversalError` on Windows. (#886, #895)

### Removed

- CI: deleted `ci-integration-pr-stub.yml`. The four stubs were a holdover from the pre-merge-gate model where branch protection required each Tier 2 check name directly. After #867, branch protection requires only `gate`, so the stubs are dead weight. Reduced `EXPECTED_CHECKS` in `merge-gate.yml` to just `Build & Test (Linux)`.

[Copilot]

The new entry says discover_policy resolves project_root before computing the cache path, but the actual fix (per #886/#895) is in _get_cache_dir() / ensure_path_within() path normalization. Consider rewording to describe the behavior change (policy cache path normalization on Windows) without attributing it to the wrong function name.

Suggested change

	- Policy cache path resolution on Windows: `discover_policy` now resolves `project_root` to its canonical long-name form before computing the cache path, preventing 8.3 short-name/long-name mismatches from triggering a false `PathTraversalError` on Windows. (#886, #895)
	- Policy cache path handling on Windows now normalises paths consistently, preventing 8.3 short-name/long-name mismatches from triggering a false `PathTraversalError`. (#886, #895)

[github-actions]

APM Review Panel Verdict

Disposition: APPROVE

---

Per-persona findings

Python Architect: This PR is a single-line documentation edit to CHANGELOG.md. No Python source files are changed. The documented fix maps to discover_policy in src/apm_cli/policy/ resolving project_root to its canonical long-name before computing the cache path -- a defensive correction that strengthens the path security posture without architectural side effects.

OO/class diagram (problem-space of the documented fix):

classDiagram
    direction LR
    class CHANGELOG {
        <<Document>>
        +Unreleased section
        +Fixed entries
    }
    class discover_policy {
        <<IOBoundary>>
        +discover_policy(project_root) Policy
        +_resolve_cache_path(project_root) Path
    }
    class PathSecurity {
        <<Pure>>
        +validate_path_segments(value, context) None
        +ensure_path_within(path, base_dir) Path
    }
    CHANGELOG ..> discover_policy : documents fix in
    discover_policy ..> PathSecurity : uses
    class CHANGELOG:::touched
    classDef touched fill:#fff3b0,stroke:#d47600
    note for discover_policy "Before fix: 8.3 short-name vs long-name mismatch\ncaused false PathTraversalError on Windows"

Loading

Execution flow (CHANGELOG contribution path):

flowchart TD
    A[PR 929: add CHANGELOG Fixed entry] --> B["[I/O] edit CHANGELOG.md Unreleased/Fixed section"]
    B --> C{Entry follows Keep-a-Changelog format?}
    C -->|yes| D["[I/O] CHANGELOG.md persisted to main"]
    D --> E[Release tooling reads Unreleased section]
    E --> F[Windows cache path fix surfaces in release notes]
    C -->|no| G[Review blocks merge]

Loading

Design patterns

• Used in this PR: none -- straight-line documentation edit; no code pattern applicable.
• Pragmatic suggestion: none -- the current shape is the simplest correct design at this scope.

Structural check: Entry is correctly placed under ## [Unreleased] -> ### Fixed. Backtick wrapping around discover_policy is correct. PR refs (#886, #895) follow the one-line-per-PR convention. No concerns.

---

CLI Logging Expert: No changes to any output path, CommandLogger, _rich_* helper, STATUS_SYMBOLS, or DiagnosticCollector. CHANGELOG.md is a documentation artifact, not a runtime output file. Zero concerns.

---

DevX UX Expert: No command surface, flag, help text, or error wording changed. The CHANGELOG entry itself is a user-facing artifact:

"Policy cache path resolution on Windows: discover_policy now resolves project_root to its canonical long-name form before computing the cache path, preventing 8.3 short-name/long-name mismatches from triggering a false PathTraversalError on Windows. (#886, #895)"

Assessment: lead outcome is clear, technical detail is accurate and warranted for a Windows-specific behavior change, and the fix improves reliability for Windows users without introducing any new friction. All review-lens checks pass (N/A for CLI surface changes). No concerns.

---

Supply Chain Security Expert: CHANGELOG.md is a documentation file; no threat surface is opened. The documented fix (resolving project_root to canonical form before cache path computation) reduces false positives in PathTraversalError on Windows without weakening the containment guarantee -- the fix moves the resolution step upstream of the security check, not past it. Fail-closed posture is preserved. No concerns.

---

Auth Expert: Not activated -- PR modifies only CHANGELOG.md with a documentation entry; no authentication, token management, credential resolution, or host-classification files are touched.

---

OSS Growth Hacker: CHANGELOG.md is a direct conversion surface (existing user -> upgrades and shares). The Windows-specific fix is a meaningful growth signal: enterprise developer segments on Windows are a material APM adoption vector, and visibly fixing platform-specific rough edges builds community trust. The entry is honest and technical.

Side-channel to CEO: the Unreleased block now contains two platform-reliability fixes in one window (#894 LD_LIBRARY_PATH PyInstaller fix, #886/#895 Windows cache path fix). This "we fix platform-specific edge cases fast" pattern is worth extracting as a theme in the next release narrative -- it differentiates APM from tools that treat Windows and ARM as second-class. Worth a one-line callout in the release post, not a blocker here.

---

CEO arbitration

All five mandatory specialists returned clean findings with no disagreements to arbitrate. Auth Expert was correctly excluded -- the PR does not touch any auth surface. The change is a well-formed, correctly placed CHANGELOG entry that follows the project's Keep a Changelog convention with accurate technical detail and proper PR attribution. The Growth Hacker's side-channel observation about cross-platform reliability as a release narrative theme is noted and will inform the next release post, but has no bearing on this PR. This is a clean approval.

---

Required actions before merge

None.

---

Optional follow-ups

• Consider grouping the two platform-reliability fixes ([BUG] apm update fails #894, Windows: _get_cache_dir flakes on tmpdir 8.3 short names (PathTraversalError) #886/fix(policy): resolve project_root before path-traversal check #895) under a "Platform reliability" sub-header or callout in the next release post to make the "APM works reliably everywhere" story visible to Windows and ARM users.
• The documented Windows fix involves canonical path resolution before the path-traversal check; a follow-up unit test asserting this behavior under a simulated 8.3 path environment (if not already covered by Windows: _get_cache_dir flakes on tmpdir 8.3 short names (PathTraversalError) #886/fix(policy): resolve project_root before path-traversal check #895) would prevent regression.

Generated by PR Review Panel for issue #929 · ● 413.6K · ◷