feat(schema): approach template v2 (template + CI checks)

[Meyanis95]

Stacked on #160. Closes the "schema validation" sequencing item from #151.

What this adds

• approaches/_template.md: replaced v1 stub (Overview / TLDR / Architecture / More details / Links) with the v2 skeleton from feat(schema): Approach template v2 — frontmatter, per-sub-approach structure, comparison table #151. Frontmatter + 6 required body sections (Problem framing / Approaches / Comparison / Persona perspectives / Recommendation / Open questions) + per-sub-approach YAML block + 10-row comparison-table template.
• scripts/validate-patterns.js: updated validateApproach():
  • REQUIRED_APPROACH_SECTIONS now lists the v2 six (was v1 ## Overview / ## Architecture)
  • RECOMMENDED_APPROACH_SECTIONS removed (v2 has no extras)
  • REQUIRED_APPROACH_FRONTMATTER added: title, status, last_reviewed, use_case, primary_patterns
  • Title-prefix check: must match ^Approach:\s

Review scope

@coderabbitai please limit review to:

1. Whether the template content matches feat(schema): Approach template v2 — frontmatter, per-sub-approach structure, comparison table #151's "New card structure at a glance" + "Proposed schema changes" sections.
2. Whether the validator changes correctly enforce v2 (section names, frontmatter required fields, title prefix).
3. CHANGELOG entry format.

Out of scope (explicitly deferred)

• scripts/schemas/approach.json (AJV-compiled JSON Schema) — inline validator checks cover load-bearing fields without it.
• Body linter validate-approach-sections.mjs from feat(schema): Approach template v2 — frontmatter, per-sub-approach structure, comparison table #151 §8 (per-sub-approach YAML enforcement, comparison-axis row check, sub_approach → heading resolution, iptf_pocs ↔ sub-approach maturity coupling). Real work; feat(schema): Approach template v2 — frontmatter, per-sub-approach structure, comparison table #151 budgets ~1 day for it.
• Strict-flip (warnings → errors). Future PR mirroring feat(schema): flip pattern validator to strict v2 #156's role for patterns.

Test plan

• Validator passes on the 9 v2-migrated approach cards (only word-count warnings on private-payments and private-identity, both < 3000 error threshold)
• Manually breaking ## Comparison (deleted from a copy of approach-private-bonds.md) trips Missing required section: ## Comparison
• Removing use_case: from frontmatter trips Missing required frontmatter field: use_case
• Mangling title to drop Approach: prefix trips Title should start with "Approach: "
• Husky pre-commit hook (terminology + validator) passes

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Introduced Approach Template v2 with standardized structure including required metadata fields (title, status, last_reviewed, use_case, primary_patterns) and consistent sections (Problem framing, Approaches, Comparison, Persona perspectives, Recommendation, Open questions).

• Chores

  • Updated approach document validation to enforce v2 structure requirements in lenient mode (warnings only).

[coderabbitai]

Warning

Rate limit exceeded

@Meyanis95 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 40 minutes and 49 seconds before requesting another review.

To continue reviewing without waiting, purchase usage credits in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 98a7d546-d07d-4350-a90b-0c2c73c1a839

📥 Commits

Reviewing files that changed from the base of the PR and between cd7dbb3 and 9c5285b.

📒 Files selected for processing (3)

• CHANGELOG.md
• approaches/_template.md
• scripts/validate-patterns.js

Walkthrough

Introduces a structured "approach card v2" template with required YAML frontmatter (title, status, last_reviewed, use_case, primary_patterns) and six standardized body sections (Problem framing, Approaches, Comparison, Persona perspectives, Recommendation, Open questions). Updates validator to enforce these sections, frontmatter fields, and a title prefix rule (Approach: ), replacing legacy template guidance.

Changes

Approach Template v2 Schema & Validation

Layer / File(s)	Summary
Template Frontmatter Schema approaches/_template.md	Introduces required frontmatter fields (title, status, last_reviewed, use_case, primary_patterns) and optional fields (related_use_cases, supporting_patterns, iptf_pocs, open_source_implementations).
Template Body Structure approaches/_template.md	Defines required body sections (Problem framing, Approaches with per-approach YAML, Comparison table, Persona perspectives, Recommendation, Open questions) with prescribed narrative subsections.
Validator Schema Definitions scripts/validate-patterns.js	Defines REQUIRED_APPROACH_SECTIONS (six fixed headings) and REQUIRED_APPROACH_FRONTMATTER (five required fields) constants for v2 enforcement.
Validator Implementation scripts/validate-patterns.js	Updates validateApproach to check v2 frontmatter fields, enforce title prefix Approach: , validate section presence and order, and remove legacy recommended-sections logic.
Changelog Documentation CHANGELOG.md	Documents v2 approach template adoption, required sections, frontmatter fields, title prefix rule, and lenient-mode validation behavior.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• ethereum/iptf-map#160: Ports nine approach cards to the same v2 schema that this PR introduces and whose validator this PR updates.
• ethereum/iptf-map#152: Implements parallel v2 template and schema changes for patterns, with similar validator updates to scripts/validate-patterns.js.

Suggested reviewers

• oskarth
• rymnc

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: introducing approach template v2 alongside CI validation checks.
Description check	✅ Passed	The description covers what is added, includes a detailed review scope, identifies out-of-scope items, and documents test results. However, it does not follow the repository's PR template structure.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/approach-schema-v2-template-ci

---

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.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@approaches/_template.md`:
- Around line 16-19: The comment incorrectly mandates iptf_pocs whenever a
sub-approach has maturity: prototyped; update the body linter and documentation
text to only require the iptf_pocs field when there is an actual IPTF-internal
prototype, not merely when maturity: prototyped is set. Locate references to
"iptf_pocs" and the maturity check logic (the body linter rule that inspects
sub-approach.maturity and the template comment block) and change the condition
to check an explicit flag/marker indicating an IPTF-built prototype (e.g., an
is_ip_tf_prototype or presence of pocs[].sub_approach entry) rather than
treating maturity: prototyped as sufficient; also update the template comment to
reflect the corrected rule.

In `@CHANGELOG.md`:
- Line 7: The CHANGELOG entry for "feat(schema): approach template v2 -- replace
[_template.md]..." is missing the required PR reference suffix; update that
entry by appending the PR number in the standard format " (`#NNN`)" to the end of
the entry title (e.g., feat(schema): ... -- ... (`#123`)), matching other
[Unreleased] entries; locate the exact entry text ("feat(schema): approach
template v2 -- replace [_template.md]...") and add the PR number accordingly.

In `@scripts/validate-patterns.js`:
- Around line 679-684: The current check uses !frontmatter[field] which treats
empty arrays (e.g., primary_patterns: []) as present; change the validation in
the REQUIRED_APPROACH_FRONTMATTER loop to explicitly detect empty arrays and
missing values: for the primary_patterns field (and any other expected-array
fields) ensure you test Array.isArray(frontmatter[field]) &&
frontmatter[field].length > 0, and for non-array fields ensure
frontmatter[field] is not null/undefined/empty string; if the value fails these
checks push the same fileWarnings message. Reference:
REQUIRED_APPROACH_FRONTMATTER, frontmatter, fileWarnings, primary_patterns.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: dec5316b-83a1-4be4-b1ee-6898cd9d373f

📥 Commits

Reviewing files that changed from the base of the PR and between 1deec0f and cd7dbb3.

📒 Files selected for processing (3)

• CHANGELOG.md
• approaches/_template.md
• scripts/validate-patterns.js

📜 Review details

🧰 Additional context used

📓 Path-based instructions (2)

CHANGELOG.md

⚙️ CodeRabbit configuration file

CHANGELOG.md: Entries must go under [Unreleased], include a markdown link to the changed file,
reference the PR number (#NNN), and use a semantic prefix (feat(pattern):, feat(vendor):, fix:, docs:, etc.).

Files:

• CHANGELOG.md

approaches/**/*.md

⚙️ CodeRabbit configuration file

approaches/**/*.md: This is an approach card.

Structure: Validate against the template at approaches/_template.md.
File naming and conventions are in approaches/README.md. Filename must start with approach- in kebab-case.

Approach cards MUST link to both the use case they address and the patterns they combine.
Flag if no pattern or use case cross-references are present.

Word limits: warn > 2000, error > 3000.

Files:

• approaches/_template.md

🧠 Learnings (3)

📚 Learning: 2026-05-06T13:50:53.704Z

Learnt from: Meyanis95
Repo: ethereum/iptf-map PR: 160
File: approaches/approach-private-trade-settlement.md:42-62
Timestamp: 2026-05-06T13:50:53.704Z
Learning: For approach Markdown cards using the v2 schema in the ethereum/iptf-map repo, treat the use_case frontmatter slug as the canonical cross-reference to the addressed use case. Do not enforce an in-body markdown link to the use case on v2 approach cards. The in-body link requirement is a v1 convention and should not be applied to v2 cards; this distinction is tracked separately. This pattern applies to all approach Markdown files under approaches/ (e.g., approaches/**/*.md). For the file approaches/approach-private-trade-settlement.md specifically, ensure it adheres to the v2 rule by using the frontmatter use_case reference and omit enforcing in-body use-case links.

Applied to files:

• approaches/_template.md

📚 Learning: 2026-05-06T13:50:59.931Z

Learnt from: Meyanis95
Repo: ethereum/iptf-map PR: 160
File: approaches/approach-private-money-market-funds.md:1-24
Timestamp: 2026-05-06T13:50:59.931Z
Learning: In iptf-map v2 approach cards, iptf_pocs is for IPTF-internal research prototypes tied to a specific sub-approach, while open_source_implementations is for third-party production-viability signals. Do not flag a missing iptf_pocs block unless an IPTF-internal prototype actually exists for that approach; a sub-approach with maturity: prototyped does not imply an IPTF PoC exists. Reviewers should: (1) verify whether an IPTF-internal prototype exists for the sub-approach in question; (2) if yes, ensure an iptf_pocs block is present and accurately describes it; (3) if no internal prototype exists, do not require an iptf_pocs block. This guideline applies to all approach markdown files under approaches/ in this repository (ethereum/iptf-map).

Applied to files:

• approaches/_template.md

📚 Learning: 2026-05-06T13:50:58.986Z

Learnt from: Meyanis95
Repo: ethereum/iptf-map PR: 160
File: approaches/approach-private-broadcasting.md:1-26
Timestamp: 2026-05-06T13:50:58.986Z
Learning: Follow the v2 schema for approach cards in approaches/**/*.md. iptf_pocs is strictly for IPTF-internal research prototypes with a matching sub_approach entry; open_source_implementations covers third-party production-viability signals. Do not flag missing iptf_pocs when there is no IPTF-internal prototype for the approach card; the field is optional and must not be fabricated.

Applied to files:

• approaches/_template.md

🪛 LanguageTool

approaches/_template.md

[grammar] ~90-~90: Ensure spelling is correct
Context: ...+ verification | | Proof gen (client) | XXXms | ### *(Repeat the structure above for each arc...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

[Meyanis95]

@coderabbitai approve

[coderabbitai]

✅ Actions performed

Comments resolved and changes approved.