feat(cli): step ask — read-only query to historical step sessions #156

2026-06-07T10:40:54Z

xiaoju commented

2026-06-07 10:40:54 +00:00

What

Adds uwf step ask <step-hash> -p "question" — a read-only query command that asks a follow-up question to a completed step's agent without mutating thread state.

Why

Closes the Phase 2b gap from issue #146: with the Phase 2a fork / session-cache infrastructure already in place, agents need a way to be re-queried about past work without polluting the immutable thread chain. Useful for clarifications and exploratory diagnostics on historical decisions.

Changes

CLI
- packages/cli/src/cli.ts — wire step ask subcommand (-p, --agent, --no-fork).
- packages/cli/src/commands/step.ts — cmdStepAsk plus helpers (parseAgentOverride, resolveAskAgentConfig, deriveAgentName, loadDetailNode, spawnAskAgent, resolveAskWorkflow, performFork).
- Read-only: no new StepNode, no thread-state mutation.
- Fork-by-default: caches new fork id under <stepHash>:ask; subsequent asks reuse it.
- --no-fork fallback: fresh session with the step's detail ref injected as context.
- Agent resolution: --agent flag → config alias for recorded agent → step's recorded raw command.
Tests
- packages/cli/src/__tests__/step-ask.test.ts — 16 cases across 6 groups (CLI validation, CAS errors, success path, fork-cache semantics, fallback path, agent resolution).
Docs
- packages/cli/README.md — step ask row + examples in the Step Commands section.
- packages/util/src/usage-reference.ts — step ask entry rendered by uwf prompt usage, with prose explaining fork-cache and --no-fork semantics.
Changeset
- .changeset/step-ask.md — @united-workforce/cli minor, @united-workforce/util patch.

Verification

pnpm run build ✓
pnpm run check (Biome + log tag validation) ✓
pnpm run typecheck ✓
pnpm run test ✓ (91 files / 867 tests, including 16 new cases)

Ref

Fixes #146

## What Adds `uwf step ask <step-hash> -p "question"` — a read-only query command that asks a follow-up question to a completed step's agent without mutating thread state. ## Why Closes the Phase 2b gap from issue #146: with the Phase 2a fork / session-cache infrastructure already in place, agents need a way to be re-queried about past work without polluting the immutable thread chain. Useful for clarifications and exploratory diagnostics on historical decisions. ## Changes - **CLI** - `packages/cli/src/cli.ts` — wire `step ask` subcommand (`-p`, `--agent`, `--no-fork`). - `packages/cli/src/commands/step.ts` — `cmdStepAsk` plus helpers (`parseAgentOverride`, `resolveAskAgentConfig`, `deriveAgentName`, `loadDetailNode`, `spawnAskAgent`, `resolveAskWorkflow`, `performFork`). - Read-only: no new `StepNode`, no thread-state mutation. - Fork-by-default: caches new fork id under `<stepHash>:ask`; subsequent asks reuse it. - `--no-fork` fallback: fresh session with the step's detail ref injected as context. - Agent resolution: `--agent` flag → config alias for recorded agent → step's recorded raw command. - **Tests** - `packages/cli/src/__tests__/step-ask.test.ts` — 16 cases across 6 groups (CLI validation, CAS errors, success path, fork-cache semantics, fallback path, agent resolution). - **Docs** - `packages/cli/README.md` — `step ask` row + examples in the Step Commands section. - `packages/util/src/usage-reference.ts` — `step ask` entry rendered by `uwf prompt usage`, with prose explaining fork-cache and `--no-fork` semantics. - **Changeset** - `.changeset/step-ask.md` — `@united-workforce/cli` minor, `@united-workforce/util` patch. ## Verification - `pnpm run build` ✓ - `pnpm run check` (Biome + log tag validation) ✓ - `pnpm run typecheck` ✓ - `pnpm run test` ✓ (91 files / 867 tests, including 16 new cases) ## Ref Fixes #146

xiaoju added 1 commit 2026-06-07 10:40:55 +00:00

feat(cli): step ask — read-only query to historical step sessions

CI / check (pull_request) Successful in 2m46s

Details

b5e094ab4d

Adds `uwf step ask <step-hash> -p <prompt>` for asking follow-up
questions to a completed step's agent without mutating thread state.

- Fork-by-default: creates and caches a fork session per step (cache
  key `<stepHash>:ask`); subsequent asks reuse it.
- `--no-fork` fallback: spawns a fresh session with the step's detail
  ref injected as context.
- `--agent` overrides the recorded agent; otherwise resolves from the
  step's agent field via config alias.
- Updates `packages/cli/README.md` and `packages/util/src/usage-reference.ts`
  so the new subcommand is discoverable via README and `uwf prompt usage`.

Fixes #146

xingyue approved these changes 2026-06-07 11:05:53 +00:00

xingyue left a comment

LGTM ✅

仔细审了代码，核心要点：

Read-only 保证 — 全程只有 CAS .get() 读取，无 put()/setThread()。唯一的写操作是 ask-session cache（独立于 CAS 层）。测试 3.2/3.3 显式验证 head 指针和 step count 不变。

Fork-cache 设计 — stepHash:ask 键隔离正确。performFork 先查缓存再 spawn，测试 4.1/4.2/4.3 覆盖了创建、复用、per-step 独立性。

Agent 解析 — 优先级链合理：--agent flag → config alias → recorded agent → raw command。

16 个测试 — 全部是真实 shell mock-agent 的集成测试，不是 import mock。6 组覆盖了 CLI 验证、CAS 错误、核心行为、fork 缓存、fallback 路径、agent 解析。

小问题记录（不阻塞合入）：

L556/L565 的 detailRef !== null guard 是 dead code（L525 已 fail 过）
L444 { stderr?: Buffer } 用了 ?:，但属于 Node.js external boundary，pragmatic
resolveAskWorkflow 标了 async 但没有 await
opts.fork !== false 双重否定可简化

小橘 solve-issue 流水线越来越成熟了 👏

LGTM ✅ 仔细审了代码，核心要点： **Read-only 保证** — 全程只有 CAS `.get()` 读取，无 `put()`/`setThread()`。唯一的写操作是 ask-session cache（独立于 CAS 层）。测试 3.2/3.3 显式验证 head 指针和 step count 不变。 **Fork-cache 设计** — `stepHash:ask` 键隔离正确。performFork 先查缓存再 spawn，测试 4.1/4.2/4.3 覆盖了创建、复用、per-step 独立性。 **Agent 解析** — 优先级链合理：--agent flag → config alias → recorded agent → raw command。 **16 个测试** — 全部是真实 shell mock-agent 的集成测试，不是 import mock。6 组覆盖了 CLI 验证、CAS 错误、核心行为、fork 缓存、fallback 路径、agent 解析。小问题记录（不阻塞合入）： 1. L556/L565 的 `detailRef !== null` guard 是 dead code（L525 已 fail 过） 2. L444 `{ stderr?: Buffer }` 用了 `?:`，但属于 Node.js external boundary，pragmatic 3. `resolveAskWorkflow` 标了 async 但没有 await 4. `opts.fork !== false` 双重否定可简化小橘 solve-issue 流水线越来越成熟了 👏

xingyue merged commit f697aec3e7 into main

2026-06-07 11:05:59 +00:00

xingyue deleted branch fix/146-step-ask

2026-06-07 11:06:00 +00:00

xiaoju referenced this issue from a commit

2026-06-07 11:51:23 +00:00

chore(cli): clean up step-ask nits from PR #156 review

xiaoju referenced this pull request

2026-06-07 11:51:49 +00:00

chore(cli): clean up step-ask nits from PR #156 review #158

xingyue referenced this issue from a commit

2026-06-07 11:57:54 +00:00