Fix frontmatter parsing, verbose workaround matching, and doc alignment by Copilot · Pull Request #4 · spazyCZ/agent-package-manager

Copilot · 2026-02-20T00:44:50Z

Five bugs/inconsistencies identified in PR review: incorrect case-sensitive matching in _print_verbose_workaround, fragile frontmatter delimiter detection, and three doc misalignments.

Code fixes

frontmatter.py — Replace str.find('---', 3) with line-by-line scan; previously any --- substring inside YAML values or body text would terminate parsing early
convert.py — Add .lower() to normalized key in _print_verbose_workaround(); VERBOSE_WORKAROUNDS keys like "alwaysApply" never matched lowercased warning strings, so --verbose workaround hints were silently suppressed

# Before: "alwaysApply" != "alwaysapply field dropped..." → no hint printed
# After:
normalized_key = key.replace("_", " ").replace("removed", "").strip().lower()
if normalized_key and normalized_key in warning_lower:

Doc fixes

mcp/index.md — Diagram showed ~/.aam/sources-cache/; actual path is ~/.aam/cache/git/
DESIGN.md — Instructions detection table omitted .github/copilot-instructions.md; scanner still detects it — added for backward-compat accuracy
platforms/copilot.md — Deployed instruction example used scope: project; Copilot consumes applyTo — updated to applyTo: "**"

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

…c paths and patterns Co-authored-by: spazyCZ <22116740+spazyCZ@users.noreply.github.com>

Copilot

Pull request overview

This PR addresses parsing and matching issues in the AAM CLI conversion flow and aligns multiple documentation examples/diagrams with current behavior and supported conventions.

Changes:

Fix YAML frontmatter parsing to locate the closing --- delimiter via a line scan instead of substring search.
Improve --verbose workaround hint matching by normalizing workaround keys to lowercase before searching warnings.
Update docs to reflect the correct Copilot applyTo field, legacy Copilot instruction detection, and the actual git cache path.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/user_docs/docs/platforms/copilot.md	Updates deployed Copilot instruction example to use `applyTo` instead of `scope`.
docs/user_docs/docs/mcp/index.md	Fixes MCP diagram cache path to `~/.aam/cache/git/`.
docs/DESIGN.md	Documents legacy `.github/copilot-instructions.md` detection pattern.
apps/aam-cli/src/aam_cli/converters/frontmatter.py	Reworks frontmatter closing-delimiter detection to be line-based.
apps/aam-cli/src/aam_cli/commands/convert.py	Normalizes workaround keys to lowercase to improve matching in verbose mode.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-20T01:00:40Z

apps/aam-cli/src/aam_cli/commands/convert.py

    for key, workaround in VERBOSE_WORKAROUNDS.items():
-        if key.replace("_", " ").replace("removed", "").strip() in warning_lower:
+        normalized_key = (
+            key.replace("_", " ")
+            .replace("removed", "")
+            .strip()
+            .lower()
+        )
+        if normalized_key and normalized_key in warning_lower:


Workaround matching is still brittle because it relies on the (normalized) workaround dict key being a substring of the warning text. Several current pairs don’t match (e.g., globs_lost vs "Glob-scoped instruction converted…", user_invokable_removed vs "user-invokable flag removed.", mcp_servers_removed vs "MCP server configuration…"). Consider standardizing warnings to include a stable token/id, or mapping explicit substrings/regexes instead of deriving from the key name.

Copilot · 2026-02-20T01:00:40Z

apps/aam-cli/src/aam_cli/commands/convert.py

 def _print_verbose_workaround(console: Console, warning: str) -> None:
    """Print verbose workaround text for a warning if available."""
    warning_lower = warning.lower()

    for key, workaround in VERBOSE_WORKAROUNDS.items():
-        if key.replace("_", " ").replace("removed", "").strip() in warning_lower:
+        normalized_key = (
+            key.replace("_", " ")
+            .replace("removed", "")
+            .strip()
+            .lower()
+        )
+        if normalized_key and normalized_key in warning_lower:
            console.print(f"      [dim]{workaround}[/dim]")
            return


There are CLI/unit tests for convert, but none assert that --verbose actually prints the expected workaround hint(s). A small test that triggers a known warning (e.g., alwaysApply dropped) and checks the hint output would cover this behavior.

Copilot · 2026-02-20T01:00:40Z

apps/aam-cli/src/aam_cli/converters/frontmatter.py

-    body = stripped[end_idx + 3:].lstrip("\n")
+    closing_idx: int | None = None
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":


The closing frontmatter delimiter check uses line.strip() == "---", which will also treat indented --- lines (e.g., inside a YAML literal block) as a delimiter and truncate parsing. Delimiters should only match when --- starts at column 0 (optionally with trailing whitespace/newline).

Suggested change

if line.strip() == "---":

# Match closing delimiter only when '---' starts at column 0

# and is followed only by optional whitespace/newline.

if line.startswith("---") and line[3:].strip() == "":

Copilot · 2026-02-20T01:00:40Z

apps/aam-cli/src/aam_cli/converters/frontmatter.py

+    # Body is everything after the closing delimiter
+    body = "".join(lines[closing_idx + 1:]).lstrip("\n")


lstrip("\n") will leave a leading \r when parsing files with CRLF line endings, so body can start with \r\n. Consider stripping both \r and \n here (and keep behavior consistent across platforms).

Copilot · 2026-02-20T01:00:41Z

apps/aam-cli/src/aam_cli/converters/frontmatter.py

-    body = stripped[end_idx + 3:].lstrip("\n")
+    closing_idx: int | None = None
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":


The new line-by-line delimiter scan changes parsing behavior but there’s no unit test covering the previously-broken case (e.g., a YAML value containing --- that should not terminate frontmatter). Adding a regression test would help prevent this from reappearing.

Suggested change

if line.strip() == "---":

# Only treat '---' as a closing delimiter when it appears at the start

# of the line (column 0) with no other non-whitespace characters.

if line.startswith("---") and line.strip() == "---":

Initial plan

532d30b

Copilot AI assigned Copilot and spazyCZ Feb 20, 2026

Copilot AI mentioned this pull request Feb 20, 2026

Update pack #3

Merged

Copilot started work on behalf of spazyCZ February 20, 2026 00:45 View session

Fix review comments: frontmatter parsing, verbose workaround case, do…

e4aab38

…c paths and patterns Co-authored-by: spazyCZ <22116740+spazyCZ@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Update pack with improved documentation and CLI features~~ Fix frontmatter parsing, verbose workaround matching, and doc alignment Feb 20, 2026

Copilot AI requested a review from spazyCZ February 20, 2026 00:52

Copilot finished work on behalf of spazyCZ February 20, 2026 00:52

spazyCZ marked this pull request as ready for review February 20, 2026 00:54

Copilot AI review requested due to automatic review settings February 20, 2026 00:54

spazyCZ merged commit 2be3990 into test Feb 20, 2026
3 checks passed

spazyCZ deleted the copilot/sub-pr-3 branch February 20, 2026 00:54

Copilot started reviewing on behalf of spazyCZ February 20, 2026 00:54 View session

Copilot AI reviewed Feb 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix frontmatter parsing, verbose workaround matching, and doc alignment#4

Fix frontmatter parsing, verbose workaround matching, and doc alignment#4
spazyCZ merged 2 commits intotestfrom
copilot/sub-pr-3

Copilot AI commented Feb 20, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

-        if line.strip() == "---":
+        # Match closing delimiter only when '---' starts at column 0
+        # and is followed only by optional whitespace/newline.
+        if line.startswith("---") and line[3:].strip() == "":

		# Body is everything after the closing delimiter
		body = "".join(lines[closing_idx + 1:]).lstrip("\n")

-        if line.strip() == "---":
+        # Only treat '---' as a closing delimiter when it appears at the start
+        # of the line (column 0) with no other non-whitespace characters.
+        if line.startswith("---") and line.strip() == "---":

Conversation

Copilot AI commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code fixes

Doc fixes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 20, 2026 •

edited

Loading