diff --git a/docs/src/content/docs/concepts/lifecycle.md b/docs/src/content/docs/concepts/lifecycle.md index 627d6afde..0d7a626e7 100644 --- a/docs/src/content/docs/concepts/lifecycle.md +++ b/docs/src/content/docs/concepts/lifecycle.md @@ -133,7 +133,7 @@ apm audit --file # standalone: scan an arbitrary file **Local mode** (`apm audit`, optionally with `--strip` or `--file `) 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 ` 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 ` it also evaluates org policy against the lockfile. **Common surprises** diff --git a/docs/src/content/docs/reference/baseline-checks.md b/docs/src/content/docs/reference/baseline-checks.md index dee4d78a3..3e083ea29 100644 --- a/docs/src/content/docs/reference/baseline-checks.md +++ b/docs/src/content/docs/reference/baseline-checks.md @@ -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 | @@ -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. @@ -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.