feat(pi-workflow): add human-readable run labels

2026-08-25 21:22:08 -04:00
parent a1d0b1415c
commit 54a7921227
17 changed files with 385 additions and 52 deletions
@@ -37,7 +37,7 @@ The assistant must inspect the current run before each state-changing call and o

 ## Inspect and continue

-Use `/workflow` for the focused-card dashboard. It lists runs attached to the current session and shows persisted status, progress, Gate, plan, report, branch, and worktree information.
+Use `/workflow` for the focused-card dashboard. It lists runs attached to the current session and shows persisted status, progress, Gate, plan, report, branch, and worktree information. Human-facing surfaces use the feature name as the run label. Analysis and legacy runs fall back to a request label of at most 48 characters, then to the run ID when no request exists. Duplicate labels in one available-run list receive ` · <run-id-prefix>`, using the shortest unique prefix of at least eight characters.

 Use `/workflow continue` to select a run with a pending fresh-session handoff or normal-compaction continuation. `/workflow resume` is an alias. A run ID may be supplied directly:

@@ -46,7 +46,7 @@ Use `/workflow continue` to select a run with a pending fresh-session handoff or
 /workflow resume <run-id>
 ```

-Selection requires interactive TUI mode. In non-interactive modes, provide the run ID.
+Selection requires interactive TUI mode. In non-interactive modes, provide the run ID. Labels are presentation-only and cannot be used as lookup aliases; copyable continue and stop commands always retain the full run ID. They require no schema migration and do not change persisted paths.

 ## Stop active work

@@ -80,7 +80,7 @@ Run state and bounded artifacts are stored under:
 ~/.pi/agent/pi-workflows/runs/<run-id>/
 ```

-Important files include immutable plan revisions, Assignment transcripts, retained prototype reports and screenshots, `result.json`, and the terminal Markdown report. Completed worktrees remain available for manual inspection and integration.
+Important files include immutable plan revisions, Assignment transcripts, retained prototype reports and screenshots, `result.json`, and the terminal Markdown report. Report headings use the readable label and include the full canonical Run ID as explicit metadata. Completed worktrees remain available for manual inspection and integration.

 ## Reload after exposure

@@ -128,6 +128,14 @@ Recent workflow events
  cache-audit     Completed        31m
 ```

+If labels collide in this available list, only the duplicates gain the shortest unique run-ID prefix (at least eight characters):
+
+```text
+> search-page · 12345678a     Plan Approval
+  search-page · 12345678b     Implement
+  cache-audit                 Completed
+```
+
 Narrow terminals preserve the same timeline and omit timestamps first.

 ## Direction criteria
@@ -137,5 +145,7 @@ The implementation should:
 - Start dark-mode friendly through Pi theme tokens.
 - Keep the default view compact and reveal paths, evidence, and transcripts on demand.
 - Show only valid actions for the current persisted Gate or continuation intent.
+- Use feature-name-first presentation labels, with bounded request fallbacks and collision suffixes only when needed.
+- Keep the full run ID out of ordinary prose while retaining it in copyable commands, structured details, and report metadata.
 - Keep run status, revision, branch, worktree, plan, report, and prototype evidence discoverable.
 - Remain usable from narrow terminals through 4K-width terminals without continuous animation.
@@ -149,13 +149,15 @@ type GateDecision =

 Feature and feature-script starts require `featureName` as a concise lowercase kebab-case name that describes what the feature does, such as `searchable-workflow-dashboard`. Analysis starts omit it. The host validates the name before persisting launch intent.

+Human-facing dashboard, selector, notification, handoff, compaction, tool, and report prose uses a shared presentation label. It prefers `featureName`; otherwise it normalizes the request to one line and bounds it to 48 characters, preserving whole words where possible and adding `…` when truncated; only a missing request falls back to `runId`. When derived labels collide within an available run list, only those labels receive ` · <prefix>`, where the run-ID prefix is the shortest unique prefix with a minimum of eight characters. This label is never persisted as identity or accepted as a lookup alias. It requires no schema migration and does not change persisted paths. The complete `runId` remains canonical for snapshots, structured fields, command arguments, paths, receipts, leases, and idempotency. Copyable `/workflow continue <run-id>` and `/workflow stop <run-id>` commands retain it, and reports include it as `Run ID` metadata beneath the readable heading.
+
 The `pi_workflow` tool calls a single internal `execute(command)` interface. `/workflow` opens the dashboard and may accept a run ID for direct inspection. `/workflow start <message>` sends the initial request through the assistant so the normal `pi_workflow` tool path owns feature naming and idempotency; in interactive TUI mode, omitting the message opens an input prompt. `/workflow continue` presents eligible pending context transitions for selection, while `/workflow continue <run-id>` continues one directly; `/workflow resume` is an alias for both forms. `/workflow stop [run-id]` aborts a non-terminal run owned by the active parent session and presents a selector when multiple owned runs are active. The misspelled `/worlflow` alias is intentionally unsupported. Continue and stop selectors require interactive TUI mode and provide direct-run-ID guidance otherwise.

 Continuation performs only a pending fresh-session handoff or normal-compaction fallback after the run is safely waiting; it cannot approve plans, select prototypes, or make other Decisions. Stop treats `running` and `waiting` runs as active and excludes terminal runs and runs owned only by historical parent sessions.

 When a run reaches a Gate, the tool returns a structured waiting view. The parent agent asks the user through its normal interaction tools, then calls `pi_workflow` with `action: "decide"`. Child agents never receive `ask_user`.

-Background runs return a run ID immediately. When they reach a Gate or settle, the extension sends one custom follow-up message with a stable delivery key to the active parent session.
+Background runs return a structured run ID immediately. When they reach a Gate or settle, the extension sends one custom follow-up message with a stable delivery key to the active parent session and a readable run label in its prose.

 After `start` creates the run lease, every subsequent state-changing parent operation is authenticated against its active parent-session ID. Session IDs retained in `parentSessionIds` are historical discovery links and permit inspection only.