feat: scope archetype file-tree signals to path context

[PrzemekGalarowicz]

Summary

• Scope classifyEntry file-tree signals to ancestor path context so basename-only matches no longer misclassify projects (e.g. src/api/ client wrappers, root seed.sql, email templates, test fixtures).
• Accept bare unquoted YAML tokens in capability applies frontmatter ([ssr, backend] parses the same as ["ssr","backend"]), with whole-token enum validation preserved.

Test plan

• npm test — path-context fixtures in tests/detect-archetype.test.ts and bare-token parsing in tests/capability-index.test.ts
• CI passes (format, lint, typecheck, test)

Made with Cursor

Summary by CodeRabbit

• New Features
  • Archetype detection now uses ancestor path context to better identify API, route, SQL, and migration-related patterns.
  • Frontmatter parsing now accepts both quoted and unquoted applies tokens.
• Bug Fixes
  • Reduced false positives from broad basename/extension matching.
  • Improved .sql and migrations/ scoping—top-level .sql no longer misclassifies as backend.
  • Invalid applies values now reliably fail validation instead of being silently ignored.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2c6f1ea5-9507-4d9c-80c7-2ef6196dc6cc

📥 Commits

Reviewing files that changed from the base of the PR and between b7dc5b6 and d62a42b.

📒 Files selected for processing (20)

• .dev/features/archetype-path-context/PLAN.md
• .dev/features/archetype-path-context/REGRESSION.md
• .dev/features/archetype-path-context/REVIEW.md
• .dev/features/archetype-path-context/SHIP.md
• .dev/features/archetype-path-context/VERIFY.md
• .dev/features/archetype-path-context/regression-report.json
• .dev/features/archetype-path-context/verify-report.json
• .dev/memory-bank/lessons-learned.md
• .pharn/pharn-dev-memory-promote/body.md
• .pharn/pharn-dev-memory-promote/candidate.json
• .pharn/pharn-dev-regress/base-results.json
• .pharn/pharn-dev-regress/head-results.json
• .pharn/pharn-dev-regress/verdict.json
• .pharn/pharn-dev-verify/results.json
• .pharn/pharn-dev-verify/verdict.json
• .pharn/writes-scope.json
• src/lib/archetype.ts
• src/lib/detect-archetype.ts
• tests/archetype.test.ts
• tests/detect-archetype.test.ts

---

📝 Walkthrough

Walkthrough

This PR adds path-context scoping to archetype detection, threads ancestor segments through traversal and classification, relaxes applies token parsing to accept bare YAML tokens, and updates the associated tests and review/verification artifacts.

Changes

Archetype path-context scoping and applies parsing relaxation

Layer / File(s)	Summary
Plan, grill, and scope docs .dev/features/archetype-path-context/PLAN.md, .dev/features/archetype-path-context/GRILL.md, .dev/memory-bank/lessons-learned.md, .pharn/pharn-dev-memory-promote/*, .pharn/writes-scope.json	Adds the feature plan, advisory grill, lesson-candidate materials, lessons-learned entry, and updated write-scope metadata.
Path-scoped archetype classification src/lib/archetype.ts, src/lib/detect-archetype.ts	Introduces classifyEntry with path-context rules and threads lowercased ancestor segments through the file-tree walk.
Archetype scoping tests tests/archetype.test.ts, tests/detect-archetype.test.ts	Adds direct classifier coverage and updates project-level expectations for scoped api, route, .sql, migrations, and UI-exclusion behavior.
Relaxed applies parsing src/lib/capability-index.ts, tests/capability-index.test.ts	Changes parseApplies to accept quoted or bare bracketed tokens and adds regression tests for unquoted, mixed, and invalid inputs.
Review and verification artifacts .dev/features/archetype-path-context/REVIEW.md, .dev/features/archetype-path-context/SHIP.md, .dev/features/archetype-path-context/VERIFY.md, .dev/features/archetype-path-context/REGRESSION.md, .dev/features/archetype-path-context/*report.json, .pharn/pharn-dev-regress/*, .pharn/pharn-dev-verify/*	Records the review outcome, ship/run summary, re-verification, regression report, and recorded gate verdicts.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• pharn-dev/pharn-cli#21: Both PRs modify the archetype detection pipeline in src/lib/archetype.ts and src/lib/detect-archetype.ts.
• pharn-dev/pharn-cli#22: Both PRs affect .sql and migrations/ backend classification rules.
• pharn-dev/pharn-cli#23: Both PRs change src/lib/capability-index.ts token parsing and validation for applies.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly captures the main change: scoping archetype file-tree signals to ancestor path context.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ 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 feat/archetype-path-context

---

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

[coderabbitai]

🧹 Nitpick comments (1)

.dev/features/archetype-path-context/PLAN.md (1)

44-56: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Document the new false-negative tradeoff.

The scoping change is described as a precision win, but it also intentionally stops classifying some nonstandard backend layouts (src/api/, non-app route roots, .sql outside DB dirs). Please call that out explicitly so reviewers can judge the heuristic with the full tradeoff in view.

Suggested wording

+ Note: this intentionally narrows a few nonstandard backend layouts; call out the false-negative tradeoff explicitly.

🤖 Prompt for 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.

In @.dev/features/archetype-path-context/PLAN.md around lines 44 - 56, Update
the archetype-path-context plan to explicitly mention the false-negative
tradeoff introduced by the new scoping rules. In the section that defines Rule 1
through Rule 4, add a brief note that these precision improvements intentionally
stop classifying some nonstandard backend layouts such as nested src/api/, route
files outside app, and .sql files outside DB-hosting directories. Keep the
wording tied to the existing rule definitions in PLAN.md so reviewers can see
the heuristic change and its expected misses together.

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

Nitpick comments:
In @.dev/features/archetype-path-context/PLAN.md:
- Around line 44-56: Update the archetype-path-context plan to explicitly
mention the false-negative tradeoff introduced by the new scoping rules. In the
section that defines Rule 1 through Rule 4, add a brief note that these
precision improvements intentionally stop classifying some nonstandard backend
layouts such as nested src/api/, route files outside app, and .sql files outside
DB-hosting directories. Keep the wording tied to the existing rule definitions
in PLAN.md so reviewers can see the heuristic change and its expected misses
together.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 215f93b7-f2e3-461b-a3f3-e196727260c8

📥 Commits

Reviewing files that changed from the base of the PR and between 186b55d and b7dc5b6.

📒 Files selected for processing (7)

• .dev/features/archetype-path-context/GRILL.md
• .dev/features/archetype-path-context/PLAN.md
• .pharn/writes-scope.json
• src/lib/capability-index.ts
• src/lib/detect-archetype.ts
• tests/capability-index.test.ts
• tests/detect-archetype.test.ts