Enhance agent path resolution for register mode project root kits

[ainetx]

Improve agent path resolution to support registered mode project root kits and add corresponding tests to ensure functionality.

Summary by CodeRabbit

• New Features

  • Agent integration now resolves registered kit paths in register mode using project-root-relative references, including .., as long as the final resolved path stays within the project root.

• Documentation

  • Updated “Discover Supported Agents” workflow guidance to match the revised kit-path resolution behavior.

• Bug Fixes

  • Improved handling of parent-traversal (..) during kit path interpretation to prevent unintended resolution outside the project root.

• Tests

  • Added regression/coverage tests for project-root-relative kit path resolution in agent generation.

[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: 2040408d-50eb-49ef-a12c-b307681d37c5

📥 Commits

Reviewing files that changed from the base of the PR and between aed337f and e193e8c.

📒 Files selected for processing (1)

• skills/studio/scripts/studio/commands/agents.py

🚧 Files skipped from review as they are similar to previous changes (1)

• skills/studio/scripts/studio/commands/agents.py

---

📝 Walkthrough

Walkthrough

Both _resolve_registered_project_relative_path and _resolve_registered_legacy_studio_path in agents.py drop their early guard that rejected paths containing .. segments, keeping only the downstream relative_to()-based containment check. Two regression tests and a documentation step are added to cover register-mode kits whose persisted path resolves via ...

Changes

Register-mode kit path resolution with .. support

Layer / File(s)	Summary
Remove .. rejection from registered kit path resolvers skills/studio/scripts/studio/commands/agents.py	Removes the early if ".." in path_obj.parts guard from _resolve_registered_project_relative_path and replaces unconditional .. rejection in _resolve_registered_legacy_studio_path with a conditional allowing normalized == "..". Containment is enforced solely by the existing relative_to(...) call. Also adds and repositions @cpt-begin/@cpt-end markers around both helpers.
Regression tests for register-mode project-root kit path tests/test_agents_coverage.py	Adds test_generate_agents_supports_register_mode_project_root_kit_path (verifies _process_single_agent shared skill output) and test_list_public_components_supports_register_mode_project_root_kit_path (verifies manifest_backed slug and resolved source/kit roots) using a temporary project with register-mode core.toml and .cf-studio-kit.toml.
Architecture doc: document .. resolution rule architecture/features/agent-integration.md	Inserts a new discovery step stating that register-mode entries persisted as .. are resolved relative to the project root and accepted when the result stays within that root; renumbers the following step.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• constructorfabric/studio#34: Both PRs modify registered-kit path resolution to handle project-root-relative paths; PR 34 adds project_root-aware containment/fallback in _load_kit_layers while this PR removes the ..-rejection guard in the downstream resolution helpers.
• constructorfabric/studio#44: Directly overlaps with this PR's changes to kit/agent path resolution logic in agents.py, including similar project-root-aware path handling and test coverage.

Poem

🐇 Hop through the dots, don't fear ..!
The containment check guards every view.
Register your kits from the root of the tree,
And let relative_to() set the path free.
No early rejection — just trust in the check! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: enhancing agent path resolution to support register mode project root kits, which matches the core objective of the PR.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-kit-gen-agents

---

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

[coderabbitai]

🧹 Nitpick comments (1)

tests/test_agents_coverage.py (1)

424-557: ⚡ Quick win

Add one negative traversal regression for register-mode kit paths.

These tests cover the intended path = ".." success path well. Add a companion case (for example path = "../..") asserting the kit is skipped/not resolved, so the containment check remains explicitly protected by tests as this guard model evolves.

🤖 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 `@tests/test_agents_coverage.py` around lines 424 - 557, Add two new negative
regression test cases to verify that the containment check prevents kits with
paths outside the project root from being resolved. Create a test method similar
to test_generate_agents_supports_register_mode_project_root_kit_path but using
path = "../.." in the core.toml configuration, then assert that the result
status is not PASS or that the generated skill file does not exist. Similarly,
add a companion test method similar to
test_list_public_components_supports_register_mode_project_root_kit_path using
path = "../.." and verify that the components list is empty or does not contain
the gears kit, ensuring the containment validation logic is explicitly covered
by regression tests as the guard model evolves.

🤖 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 `@tests/test_agents_coverage.py`:
- Around line 424-557: Add two new negative regression test cases to verify that
the containment check prevents kits with paths outside the project root from
being resolved. Create a test method similar to
test_generate_agents_supports_register_mode_project_root_kit_path but using path
= "../.." in the core.toml configuration, then assert that the result status is
not PASS or that the generated skill file does not exist. Similarly, add a
companion test method similar to
test_list_public_components_supports_register_mode_project_root_kit_path using
path = "../.." and verify that the components list is empty or does not contain
the gears kit, ensuring the containment validation logic is explicitly covered
by regression tests as the guard model evolves.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b409867d-d012-4166-9879-3fec04fbe268

📥 Commits

Reviewing files that changed from the base of the PR and between 8ca0fbe and aed337f.

📒 Files selected for processing (3)

• architecture/features/agent-integration.md
• skills/studio/scripts/studio/commands/agents.py
• tests/test_agents_coverage.py

[sonarqubecloud]

Quality Gate failed

Failed conditions
54.3% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud