fix(yaml_io): validate line-1 delimiter before parsing Markdown frontmatter (#2663)

.apm/architecture/owners/contracts-tooling.json

@@ -31,8 +31,8 @@
     },
     {
       "id": "frontmatter-bom-bounded-yaml",
-      "decision": "Frontmatter BOM decoding and bounded YAML parsing",
-      "owner": "utils/yaml_io.py (load_frontmatter, _BoundedYAMLHandler)",
+      "decision": "Frontmatter delimiter detection, BOM decoding, and bounded YAML parsing",
+      "owner": "utils/yaml_io.py (load_frontmatter, loads_frontmatter, _BoundedYAMLHandler)",
       "selectors": ["src/apm_cli/utils/yaml_io.py"],
       "guards": ["contracts-tooling-frontmatter-yaml"]
     },

CHANGELOG.md

@@ -15,6 +15,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- `apm install` no longer silently drops instruction Markdown whose
+  unfenced bodies contain `---` horizontal rules. It now stops the whole package
+  before deploying any primitive when instruction frontmatter is invalid YAML or
+  decodes critical hidden characters. `--force` overrides only the critical
+  character finding, never malformed YAML; warning-level findings do not block.
+  (by @manideep-malyala, #2666)
 - `apm pack` now reports unavailable remote package metadata, exposes
   certifiability in JSON, prevents `--check-clean` from certifying degraded
   regeneration, and lets `--strict-metadata` fail before writes. (closes #2524)

docs/src/content/docs/producer/author-primitives/index.md

@@ -43,10 +43,11 @@ See the [targets matrix](../../reference/targets-matrix/) for the full map.
 
 Commands ship as prompts (`.apm/prompts/*.prompt.md`); there is no separate `.apm/commands/` directory. See [Hooks and commands](./hooks-and-commands/).
 
-Every primitive type follows the same pattern: a markdown file (or directory containing a primary markdown file) with frontmatter declaring its name and its trigger conditions. `apm compile` reads `.apm/`, applies any policy, and writes per-target output to the right directories on the target's filesystem.
+Markdown-based primitive types use a markdown file (or directory containing a primary markdown file). Frontmatter requirements vary by primitive type and declare metadata such as the primitive's name and trigger conditions. `apm compile` reads `.apm/`, applies any policy, and writes per-target output to the right directories on the target's filesystem.
 
-Encode primitive Markdown as UTF-8. APM accepts files with or without a
-leading UTF-8 BOM and strips the BOM before parsing frontmatter.
+:::note[Frontmatter fence]
+Encode primitive Markdown as UTF-8. When a Markdown primitive has frontmatter, its opening fence of at least three hyphens (for example, `---`) must be the first content on line 1; an optional UTF-8 BOM may precede it and is stripped before parsing. Without that opening fence, APM treats the document as body content and later `---` lines remain Markdown horizontal rules. Malformed instruction frontmatter stops the package before deployment. Critical hidden characters decoded from metadata also prevent installation by default; `--force` overrides only that critical finding, while warning-level findings do not prevent installation. See [`apm install`](../../reference/cli/install/#behavior).
+:::
 
 ## Recommended reading order
 

docs/src/content/docs/reference/cli/install.md

@@ -125,6 +125,12 @@ in `apm.yml`, then run `apm install` again.
   replacements to isolated staging paths and validate them before publication.
   If download, validation, or activation fails, APM keeps the previous package
   and lockfile active and exits non-zero with retry guidance.
+- **Instruction frontmatter preflight.** Malformed YAML always rejects the
+  package before any of its primitives are deployed. Critical hidden characters
+  decoded from metadata also prevent installation by default; `--force`
+  overrides only that critical finding. Warning-level findings do not prevent
+  installation. See [Author primitives](../../../producer/author-primitives/)
+  for fence and UTF-8 BOM syntax.
 - **MCP-only lock state.** A normal project install creates or updates `apm.lock.yaml` when `apm.yml` declares only MCP dependencies, records the resolved MCP configs and targets, and migrates a legacy `apm.lock` first. Repeating the same install leaves the lockfile and target configs byte-identical. If initial lock creation fails, install exits nonzero and warns with writable-directory and rerun guidance.
 - **Lockfile replay and Git ref freshness.** Plain and `--frozen` installs may trust `apm.lock.yaml` and the local Git cache, reusing the locked commit for unchanged Git dependencies across the full resolved graph. In contrast, `apm install --update`, `apm install --refresh`, [`apm update`](../update/) with or without `--force`, [`apm lock --update`](../lock/), and [`apm outdated`](../outdated/) establish mutable Git refs from upstream instead of accepting stale refs from a local bare Git cache. APM picks up upstream changes to a transitive package's `apm.yml` only when you regenerate the graph -- run `apm update` or `apm lock --update`. See the [lockfile specification](../../lockfile-spec/) for the replay contract.
 - **Semver ranges on git deps.** `ref:` accepts semver ranges (`^1.2.0`, `~1.4`, `>=2.0 <3`, `1.5.x`) for git-source deps, including positional virtual-subdirectory references. APM runs `git ls-remote` against the dep, picks the highest tag matching the range, and pins the resolved tag plus commit SHA, version, and original constraint in `apm.lock.yaml`. Subsequent installs replay the lockfile without network; use `--update` (or change the manifest constraint) to re-resolve. See [manage dependencies](../../../consumer/manage-dependencies/#pin-a-semver-range) for the supported syntax.

packages/apm-guide/.apm/skills/apm-usage/package-authoring.md

@@ -299,8 +299,16 @@ correctly -- the component just records NOASSERTION (genuinely unknown).
 This warning fires only on the **authoring** path (your own `apm.yml`);
 installing or exporting other people's dependencies is silent.
 
-Encode primitive Markdown as UTF-8. APM accepts files with or without a
-leading UTF-8 BOM and strips the BOM before parsing frontmatter.
+Encode primitive Markdown as UTF-8. Frontmatter requirements vary by Markdown
+primitive type. When frontmatter is present, its opening fence of at least
+three hyphens (for example, `---`) must be the first content on line 1; an
+optional UTF-8 BOM may precede it and is stripped before parsing. Without that
+opening fence, APM treats the whole document as body content, and later `---`
+lines stay Markdown horizontal rules. Malformed instruction frontmatter stops
+the package before any primitive is deployed. Critical hidden characters
+decoded from metadata also prevent installation by default; `--force`
+overrides only that critical finding, while warning-level findings do not
+prevent installation.
 
 ## The 7 primitive types