@odla-ai/cli 0.30.1 → 0.30.2

package/dist/index.js

@@ -56,7 +56,7 @@ import {
   startHostedSecurityJob,
   surfacePaths,
   validateInvocation
-} from "./chunk-7V7WVTDT.js";
+} from "./chunk-3HFNKDZV.js";
 import {
   exitCodeFor,
   redactSecrets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.30.1",
+  "version": "0.30.2",
   "description": "Agent-operable CLI for odla provisioning, calendar consent and connection lifecycle, System AI administration, Worker secrets, security jobs, and smoke checks.",
   "license": "MIT",
   "homepage": "https://odla.ai/docs/packages/cli",

package/skills/odla/references/pm-work-intake.md

@@ -81,10 +81,19 @@ do not retry with a guessed revision. Once claimed, use the repository's
 worktree procedure and mention the PM references in the execution chat:
 
 ```text
-@[Task title](pm:task/<task-id>)
-@[Goal title](pm:goal/<goal-id>)
+[Task title](https://odla.ai/studio/pm/board/<task-id>)
+[Goal title](https://odla.ai/studio/pm/goals/<goal-id>)
 ```
 
+In user-facing chat, a UUID is never the record's label. Name the type and title
+as a Markdown link to Studio, then add the state, consequence, or next action. A
+useful handoff says, for example, `Ready task: [Replace UUID-only PM
+handoffs](https://odla.ai/studio/pm/board/<task-id>) — ready to claim`, not
+`Ready task: <task-id>`. When several records are related, explain that
+relationship instead of returning an id inventory. Create and lifecycle
+commands print the title-first link directly; `pm ... link <id>` reproduces it
+later. Reserve `pm ... ref <id>` for structured odla Discussion markup.
+
 ## 5. Execute, review, and complete
 
 - Keep the task description/acceptance criteria current under its revision.

package/skills/odla/references/pm.md

@@ -188,6 +188,41 @@ npx @odla-ai/cli pm task comments <task-id>
 Use `pm:task`, `pm:goal`, `pm:decision`, `pm:bug`, and `pm:runbook`. The message
 is communication; the referenced PM row remains the lifecycle authority.
 
+### Human-readable handoffs
+
+A PM id is an implementation handle, not a useful description of work. In every
+chat update, final response, review request, or handoff, lead with the record's
+type and title as an ordinary Markdown link to its Studio record, then say what
+happened or what the recipient should do. The UUID belongs in the link target,
+not in the prose. Typed `pm:*` references are for odla Discussion, where they
+render as PM chips; do not expose that internal markup in ordinary chat.
+
+Do not write:
+
+```text
+Accepted decision: 019fd392-1217-754c-a61d-3b0470bcd269
+Ready task: 019fd392-dd02-7312-86d6-d255c5a983e7
+Backup bug: 20f38d3d-7c02-54b5-8e33-f8b82e4ab125
+```
+
+Write a compact semantic handoff instead:
+
+```text
+Accepted decision: [Keep the legacy fallback through migration](https://odla.ai/studio/pm/decisions/<decision-id>) — rules out deleting it before production evidence is clean.
+Ready task: [Replace UUID-only PM handoffs](https://odla.ai/studio/pm/board/<task-id>) — implementation is bounded and ready to claim.
+Tracked bug: [PM create output hides the record title](https://odla.ai/studio/pm/bugs/<bug-id>) — retained if the task does not cover every output path.
+```
+
+The CLI reinforces this convention: successful creates and lifecycle changes
+print title-first, copy-ready links, such as
+`created bug: [Checkout 500s on retry](https://odla.ai/studio/pm/bugs/<bug-id>)`
+and `decision: [Keep the fallback](https://odla.ai/studio/pm/decisions/<decision-id>)
+→ accepted`. Use `pm ... link <id>` to regenerate an ordinary Markdown link
+later; use `pm ... ref <id>` only for structured odla Discussion markup.
+Summarize the relationship between records instead of merely listing them; PM
+contains the detail, while chat should make the state and next action
+understandable before the recipient follows a link.
+
 In Studio, open any PM item and choose **Discuss** to open the owning project's
 Discussion composer with the same stable reference already inserted. The draft
 is retained in the URL across reload/back navigation but is not a write: review,