Clarify --path semantics for agents and add safe guardrails #140

Problem

During automated multi-repo workflows, pm --path <repo> is easy to misread as "run pm against this workspace path".

In practice, --path sets the tracker storage path itself, so using a repo root can silently create root-level tracker artifacts (e.g. history/, runtime/, tasks/, schema/, settings.json) outside the expected .agents/pm location.

This is technically correct behavior, but it is a high-friction UX trap for coding agents and scripts operating across many repositories.

Repro

1. In any git repo with an existing .agents/pm, run:
   • pm --path /path/to/repo init --yes
2. Observe new tracker folders/files created at repo root instead of updating the existing tracker location.

Expected

• Strongly disambiguated flag semantics for agents/scripts.
• Lower chance of accidental tracker-root creation in repository roots.

Suggested improvements

1. Add explicit --pm-path alias and prefer it in help/examples.
2. Keep --path for backward compatibility, but mark it as tracker-path-only in command help text.
3. Add a guardrail warning (or --force) when --path points to a directory that looks like a code workspace (.git present, package manifest present, .agents/pm present, etc.).
4. Optionally add a dedicated workspace-target flag (e.g. --cwd or --workspace) for command execution context, so scripts never need to overload --path.

Why this matters for agent UX

• Reduces accidental side effects in batch automation.
• Improves predictability and token efficiency (fewer retries/repairs).
• Makes scripted usage safer across large multi-repo waves.