fix-dir-flag — Workgraph live mirror

Metadata

Status	abandoned
Assigned	`agent-1381`
Agent identity	`f51439356729d112a6c404803d88015d5b44832c6c584c62b96732b63c2b0c7e`
Created	2026-05-01T18:49:09.358273337+00:00
Started	2026-05-01T18:49:49.081206336+00:00
Tags	`fix,docs,paths,cli`, `eval-scheduled`

Description

fix-replace-stale (commit 785bc5a32) updated docs/COMMANDS.md, bundled quickstart, agent-guide, etc. to use .wg/ instead of .workgraph/. But it missed the clap CLI annotation for the -d / --dir flag, which still emits:

$ wg --help
  -d, --dir <PATH>    Workgraph directory [default: .workgraph]

This is misleading: the actual project-discovery resolver prefers .wg/ (per wg init --help's 'Resolver precedence: --dir > $WG_DIR > project discovery (.wg preferred, legacy .workgraph accepted) > global (~/.wg preferred) > ./.wg'). The clap default_value is essentially dead — the resolver overrides it for project-local discovery — but agents reading --help see .workgraph and infer that's the canonical layout.

User report 2026-05-01: a codex agent in another project read wg --help, assumed .workgraph was the directory, ran commands against a non-existent path, then had to backtrack and pass --dir .wg explicitly. The user's reaction: 'thought .workgraph was purged?'

Fix

Find the clap definition of the --dir flag (likely src/cli.rs) and update:

default_value = ".workgraph" → either default_value = ".wg" (matches new canonical) OR remove the default entirely and let the resolver own all discovery (cleaner — there's no reason for clap to advertise a default that the resolver overrides)

Update help text from:

Workgraph directory [default: .workgraph] → Workgraph directory (default: discovers .wg or legacy .workgraph in project root)

Make the help text accurate to the actual resolver behavior, not a misleading static default.

Validation

wg --help shows -d, --dir <PATH> WITHOUT mentioning '.workgraph' as the default
Help text accurately describes the resolver: 'discovers .wg or legacy .workgraph'
grep across the codebase: zero default_value = ".workgraph" (or equivalent string-literal) remaining in source
Live smoke: run wg list in /home/erik/workgraph (which has .wg/) without --dir flag — works fine (resolver finds .wg/)
Live smoke: run wg list in a directory with neither .wg/ nor .workgraph/ — gets a clear error pointing at wg init
No regression of any other flag's help text
cargo build + cargo test pass
cargo install --path . was run before claiming done

Process note

This is the second 'doc-sync missed a thing' bug today (after .workgraph paths in COMMANDS.md). The doc-sync function template should be amended to include 'grep src/cli.rs and other clap-annotated source files for stale path references' as part of audit-terminology-consistency. That amendment is small enough to fold in here OR file separately. Recommend folding in: this task adds a one-line addition to .wg/functions/doc-sync.yaml so future doc-sync runs catch this regression class.

## Description
`fix-replace-stale` (commit 785bc5a32) updated docs/COMMANDS.md, bundled quickstart, agent-guide, etc. to use `.wg/` instead of `.workgraph/`. But it missed the clap CLI annotation for the `-d / --dir` flag, which still emits:

```
$ wg --help
  -d, --dir <PATH>    Workgraph directory [default: .workgraph]
```

This is misleading: the actual project-discovery resolver prefers `.wg/` (per `wg init --help`'s 'Resolver precedence: --dir > $WG_DIR > project discovery (.wg preferred, legacy .workgraph accepted) > global (~/.wg preferred) > ./.wg'). The clap `default_value` is essentially dead — the resolver overrides it for project-local discovery — but agents reading `--help` see `.workgraph` and infer that's the canonical layout.

User report 2026-05-01: a codex agent in another project read `wg --help`, assumed `.workgraph` was the directory, ran commands against a non-existent path, then had to backtrack and pass `--dir .wg` explicitly. The user's reaction: 'thought .workgraph was purged?'

## Fix

Find the clap definition of the `--dir` flag (likely src/cli.rs) and update:
- `default_value = ".workgraph"` → either `default_value = ".wg"` (matches new canonical) OR remove the default entirely and let the resolver own all discovery (cleaner — there's no reason for clap to advertise a default that the resolver overrides)

Update help text from:
- `Workgraph directory [default: .workgraph]` → `Workgraph directory (default: discovers .wg or legacy .workgraph in project root)`

Make the help text accurate to the actual resolver behavior, not a misleading static default.

## Validation
- [ ] `wg --help` shows `-d, --dir <PATH>` WITHOUT mentioning '.workgraph' as the default
- [ ] Help text accurately describes the resolver: 'discovers .wg or legacy .workgraph'
- [ ] grep across the codebase: zero `default_value = ".workgraph"` (or equivalent string-literal) remaining in source
- [ ] Live smoke: run `wg list` in /home/erik/workgraph (which has .wg/) without --dir flag — works fine (resolver finds .wg/)
- [ ] Live smoke: run `wg list` in a directory with neither .wg/ nor .workgraph/ — gets a clear error pointing at `wg init`
- [ ] No regression of any other flag's help text
- [ ] cargo build + cargo test pass
- [ ] cargo install --path . was run before claiming done

## Process note
This is the second 'doc-sync missed a thing' bug today (after .workgraph paths in COMMANDS.md). The doc-sync function template should be amended to include 'grep src/cli.rs and other clap-annotated source files for stale path references' as part of audit-terminology-consistency. That amendment is small enough to fold in here OR file separately. Recommend folding in: this task adds a one-line addition to .wg/functions/doc-sync.yaml so future doc-sync runs catch this regression class.

Depends on

done .assign-fix-dir-flag

Required by

(none)

Log

2026-05-01T18:49:09.340609433+00:00 Task paused
2026-05-01T18:49:21.468911923+00:00 Task published
2026-05-01T18:49:42.965298932+00:00 Lightweight assignment: agent=Careful Programmer (f5143935), exec_mode=full, context_scope=task, reason=Careful Programmer matches code-fix task with precision-critical CLI annotations, extensive validation checklist, and regression risk.
2026-05-01T18:49:49.081217415+00:00 Spawned by coordinator --executor claude --model opus
2026-05-01T18:49:55.365937659+00:00 Starting: investigating clap --dir flag default value
2026-05-01T18:50:31.841315510+00:00 Task abandoned