PDX-515: fix(mcp): additive org_describe workspace discovery (no regression)

[mrdailey99]

Summary

provar_org_describe was still returning a structured cache-miss for users whose Provar test project lives inside its IDE workspace (workspace = the project's parent dir). PDX-515 (1.6.3) fixed the SfObject cache parsing, but workspace discovery only probed a sibling workspace-<basename>/ dir, so for the parent-layout the workspace was never found and the improved parser never ran.

This PR builds on @Provar-tarunprashar's fix from #232 (his commit is preserved here) and makes discovery additive so it also can't regress the older sibling layout.

What changed

workspaceCandidates() now probes, in order — each gated on the candidate actually being a Provar workspace (contains .metadata) and within --allowed-paths:

1. <parent>/ — project inside its workspace (current Provar IDE layout) ← the reported fix
2. <parent>/workspace-<basename>/ — sibling layout (restored for backward compatibility)
3. <parent>/Provar_Workspaces/workspace-<basename>/
4. ~/Provar/workspace-<basename>/

Parent is preferred (it's the real IDE layout the reporter confirmed); the sibling probe is restored right after it, so sibling-layout workspaces stay discoverable. The .metadata gate means no candidate is a false-positive "fault path" — a bare parent dir without .metadata falls through cleanly.

Why (root cause)

PDX-515 = parsing fix; #232 = discovery fix. #232 alone replaced the sibling candidate, which would regress anyone on the previously-documented sibling layout. Making it additive fixes the reported case and keeps existing sibling workspaces working.

Validation

Reproduced the customer's real layout (project inside workspace + PDX-515 SfObject cache) and ran the same end-to-end test against both code versions:

• develop / PDX-515 only → discoverWorkspace returns null → cache miss (fails)
• this branch → resolves the parent workspace, returns the object + fields (passes)

Also added a sibling-only regression test proving candidate 2 still resolves when the parent isn't a workspace.

Review notes

An adversarial Codex review of #232 flagged two issues, both addressed here:

• [high] sibling workspaces no longer discoverable → fixed by the additive candidate list + regression test.
• [medium] the registered MCP tool description still advertised the removed algorithm (<name-dashes>) → synced to the real four-candidate order (docs/mcp.md updated to match).

Jira

https://provartesting.atlassian.net/browse/PDX-515 (reopen for the parent-layout / sibling-compat cases)

Test plan

• tsc --noEmit clean
• full mocha suite — 1512 passing, 0 failing (incl. new 4-candidate + sibling-only tests)
• yarn lint clean (eslint + script-name check)
• pre-push yarn build && yarn test passed
• mcp-smoke.cjs — runs against the installed global package, not this build; env-only check

Changes

• src/mcp/tools/orgDescribeTools.ts: additive workspaceCandidates; synced in-tool description + doc comments
• docs/mcp.md: four-candidate discovery list; corrected workspace_path output description
• test/unit/mcp/orgDescribeTools.test.ts: 4-candidate order test; sibling-only back-compat regression test

Note

Supersedes #232 — that PR can be closed in favour of this one (its commit is included here). Credit to @Provar-tarunprashar for the root-cause analysis and the discovery fix.

🤖 Generated with Claude Code

[github-actions]

Quality Orchestrator

🟢 LOW · 2 / 100 · All changed files have mapped tests.

---

🧪 Tests to Run · Running 1 of 57 tests

• unit/mcp/orgDescribeTools.test.ts

▶ Run command

npx vitest run \
  unit/mcp/orgDescribeTools.test.ts

---

_{⚡ quality-orchestrator  ·  /qo stub <file>  ·  qo analyze-local}