Skip to content

[docs] Update documentation for features from 2026-05-14 #1315

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
danielmeppiel wants to merge 1 commit into from
Closed

[docs] Update documentation for features from 2026-05-14 #1315

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/src/content/docs/concepts/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ apm audit --file <path> # standalone: scan an arbitrary file

**Local mode** (`apm audit`, optionally with `--strip` or `--file <path>`) scans installed primitives -- or any file you point at -- for hidden Unicode and reports findings as text, JSON, SARIF, or markdown. With `--strip`, it removes hidden characters in place, preserving emoji and whitespace. Use `--dry-run` to preview the strip.

**CI mode** (`apm audit --ci`) runs the eight baseline consistency checks in order: `lockfile-exists`, `ref-consistency`, `deployed-files-present`, `no-orphaned-packages`, `skill-subset-consistency`, `config-consistency`, `content-integrity`, and `includes-consent`. After those pass, it performs an install-replay drift check. APM rebuilds the deployed context in a scratch directory and diffs it against your working tree, catching hand-edits to `apm_modules/` or generated files before they ship. Pass `--no-drift` to skip the replay in performance-constrained loops; pass `--no-fail-fast` to run all checks even after a failure. With `--policy <source>` it also evaluates org policy against the lockfile.
**CI mode** (`apm audit --ci`) runs the baseline consistency checks in order: `manifest-parse` (only when `apm.yml` is unparseable), `manifest-missing` (only when `apm.yml` is absent but APM artifacts exist), `lockfile-exists`, `ref-consistency`, `deployed-files-present`, `no-orphaned-packages`, `skill-subset-consistency`, `config-consistency`, `content-integrity`, and `includes-consent`. After those pass, it performs an install-replay drift check. APM rebuilds the deployed context in a scratch directory and diffs it against your working tree, catching hand-edits to `apm_modules/` or generated files before they ship. Pass `--no-drift` to skip the replay in performance-constrained loops; pass `--no-fail-fast` to run all checks even after a failure. With `--policy <source>` it also evaluates org policy against the lockfile.

**Common surprises**

Expand Down
10 changes: 9 additions & 1 deletion docs/src/content/docs/reference/baseline-checks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ first failure to skip expensive I/O.
| ID | Severity | Source | Always on? |
|---|---|---|---|
| `manifest-parse` | block | `ci_checks.py` | only when `apm.yml` cannot be parsed |
| `manifest-missing` | warn / block | `ci_checks.py` | only when `apm.yml` is absent but APM artifacts exist |
| `lockfile-exists` | block | `ci_checks.py` | yes |
| `ref-consistency` | block | `ci_checks.py` | yes |
| `deployed-files-present` | block | `ci_checks.py` | yes |
Expand All @@ -57,6 +58,13 @@ the [policy schema](../policy-schema/).
- **Effect.** Skips every other check and exits `1`. This is the only check that runs before the lockfile gate.
- **Remediation.** Fix the YAML syntax error reported in the message and re-run.

### `manifest-missing`

- **What it verifies.** That `apm.yml` is not absent while APM artifacts still exist on disk. Absent artifacts (`.apm/` directory, `apm.lock.yaml`, or the legacy `apm.lock`) with no `apm.yml` are evidence that the manifest may have been deleted to bypass policy and baseline enforcement.
- **Fails when.** `apm.yml` is absent **and** at least one of `.apm/`, `apm.lock.yaml`, or `apm.lock` is present **and** the audit is running in CI mode (`apm audit --ci`). Outside CI mode the check is advisory (passes with a warning message).
- **Effect.** In CI mode (`--ci`), exits `1` and stops further checks. In non-CI mode, records the check as passed with an informational message.
- **Remediation.** Restore `apm.yml` from version control. If the project intentionally has no APM manifest, remove the orphaned `.apm/` directory and lockfile.

### `lockfile-exists`

- **What it verifies.** That `apm.lock.yaml` is present whenever the project has APM or MCP dependencies, or whenever an existing lockfile records local content under the synthesized self-entry.
Expand Down Expand Up @@ -119,7 +127,7 @@ the [policy schema](../policy-schema/).

## Run order and fail-fast

The aggregate runner in `run_baseline_checks` evaluates checks in this order: `manifest-parse` (only when `apm.yml` is unparseable), `lockfile-exists`, `ref-consistency`, `deployed-files-present`, `no-orphaned-packages`, `skill-subset-consistency`, `config-consistency`, `content-integrity`, `includes-consent`. Drift is invoked separately by the audit command after the baseline batch.
The aggregate runner in `run_baseline_checks` evaluates checks in this order: `manifest-parse` (only when `apm.yml` is unparseable), `manifest-missing` (only when `apm.yml` is absent but APM artifacts exist), `lockfile-exists`, `ref-consistency`, `deployed-files-present`, `no-orphaned-packages`, `skill-subset-consistency`, `config-consistency`, `content-integrity`, `includes-consent`. Drift is invoked separately by the audit command after the baseline batch.

With fail-fast on (the default), the runner stops at the first failing check. `apm audit --ci --no-fail-fast` evaluates every check so the report lists every problem at once.

Expand Down
Loading