feat: read frontmatter scalars from metadata.* with top-level fallback

[LadyBluenotes]

Adds readScalarField(fm, key), which reads a skill frontmatter scalar from metadata.<key> and falls back to the top-level <key>. A string under metadata wins; non-string metadata values fall back to the top level.

Wires it into the frontmatter readers:

• scanner.ts — type, framework
• staleness.ts — library_version
• commands/validate.ts — type (framework requires check)

Backward-compatible: top-level scalars resolve as before; metadata.*-nested scalars now also resolve. Array fields (sources, requires) stay top-level.

Closes #159

Summary by CodeRabbit

Release Notes

• Bug Fixes
  • Improved backward compatibility for skill metadata. Skill configuration now supports both legacy top-level fields and new nested metadata structure, ensuring all existing skills continue to work correctly during format migration. Validation and version tracking honor both formats.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9df749d0-0aa0-49e5-9fb7-81c0b242b5aa

📥 Commits

Reviewing files that changed from the base of the PR and between 2c17c9f and 014ab69.

📒 Files selected for processing (9)

• .changeset/thin-candies-accept.md
• packages/intent/src/commands/validate.ts
• packages/intent/src/scanner.ts
• packages/intent/src/staleness.ts
• packages/intent/src/utils.ts
• packages/intent/tests/cli.test.ts
• packages/intent/tests/read-scalar-field.test.ts
• packages/intent/tests/scanner.test.ts
• packages/intent/tests/staleness.test.ts

---

📝 Walkthrough

Walkthrough

Adds readScalarField utility to packages/intent/src/utils.ts that reads scalar YAML frontmatter fields from metadata.* first, falling back to top-level keys. Wires this helper into scanner.ts, staleness.ts, and validate.ts for type, framework, and library_version fields. Adds unit tests for the helper and integration tests for scanner, staleness, and CLI validation covering both frontmatter shapes.

Changes

Back-compat metadata.* frontmatter reader

Layer / File(s)	Summary
readScalarField helper and unit tests packages/intent/src/utils.ts, packages/intent/tests/read-scalar-field.test.ts	Exports readScalarField(fm, key) that prefers metadata[key] when metadata is a non-array object, falls back to top-level fm[key], and returns undefined otherwise. Unit tests cover legacy top-level, new metadata.*, precedence, non-string values, null input, and empty-string preservation.
Wiring into scanner, staleness, and validate packages/intent/src/scanner.ts, packages/intent/src/staleness.ts, packages/intent/src/commands/validate.ts	Imports and uses readScalarField in readSkillEntry for type and framework, in checkStaleness for library_version, and in runValidateCommandInternal for the framework-skill requires check — replacing inline typeof ... === 'string' guards and direct field casts.
Integration tests and changeset packages/intent/tests/scanner.test.ts, packages/intent/tests/staleness.test.ts, packages/intent/tests/cli.test.ts, .changeset/thin-candies-accept.md	Scanner tests assert metadata.* reading and metadata.type precedence over legacy top-level. Staleness test verifies metadata.library_version drives drift classification. CLI test asserts exit code 1 and error message when metadata.type is framework but requires is absent. Changeset marks a patch release.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• #159 (Back-compat frontmatter reader for metadata-nested fields): This PR directly implements the back-compat reading of type, framework, and library_version from metadata.* with top-level fallback in scanner, staleness, and validate — the exact behavior described in the issue.
• #160: The PR implements the metadata.* fallback reading that enables the spec-compliance field migration described in that issue.

Suggested reviewers

• KevinVandy

🐇 A rabbit hops through YAML fields,
first checks metadata, then yields
to top-level keys with a gentle fall —
both old and new shapes, it handles all!
readScalarField leaps without a care,
back-compat magic hopping through the air. 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title concisely and accurately describes the main change: adding support for reading frontmatter scalar fields from metadata.* with top-level fallback for backward compatibility.
Description check	✅ Passed	The PR description clearly outlines the new readScalarField function, its integration into three frontmatter readers, backward compatibility, and links to issue #159, matching the template structure.
Linked Issues check	✅ Passed	The PR fully addresses issue #159 by implementing backward-compatible readers for scalar fields (type, framework, library_version) in both old (top-level) and new (metadata-nested) shapes across scanner.ts, staleness.ts, and validate.ts.
Out of Scope Changes check	✅ Passed	All changes are scoped to the requirements in issue #159: new readScalarField utility, integration into frontmatter readers, backward-compat tests, and a changeset entry. No unrelated changes detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch f1-back-compat-metadata-reader

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing f1-back-compat-metadata-reader (014ab69) with main (2c17c9f)}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 014ab69

---

☁️ Nx Cloud last updated this comment at 2026-06-14 19:39:08 UTC

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 014ab69

---

☁️ Nx Cloud last updated this comment at 2026-06-14 20:07:48 UTC