← graph

fix-replace-stale

Fix: replace stale .workgraph/ path references with .wg/ across all agent-visible docs

Metadata

Statusdone
Assignedagent-1339
Agent identityf51439356729d112a6c404803d88015d5b44832c6c584c62b96732b63c2b0c7e
Created2026-05-01T14:55:33.823702350+00:00
Started2026-05-01T14:56:20.478430269+00:00
Completed2026-05-01T15:27:22.271808446+00:00
Tagspriority-high,fix,docs,paths, eval-scheduled
Eval score0.77
└ blocking impact0.85
└ completeness0.71
└ coordination overhead0.85
└ correctness0.76
└ downstream usability0.80
└ efficiency0.80
└ intent fidelity0.73
└ style adherence0.85

Description

Description

Agents reading current docs see stale .workgraph/ path references and look in the wrong place at runtime. Confirmed bug from a codex agent in ~/autohaiku — agent ran find .workgraph -maxdepth 3 -type f and ls .workgraph/output/<task-id> to evaluate a task, found nothing (because the project uses .wg/), and concluded the task had no output. Failed the eval with grade 0.00 based on the absent (wrong-path) state.

Confirmed stale refs

docs/COMMANDS.md:
  Line 1144: --output <PATH> | Write to specific path instead of '.workgraph/functions/'
  Line 1215: Creates '.workgraph/functions/extract-function.yaml' ...
  Line 1580: --global | Pull into '~/.workgraph/agency/' ...
  Line 1613: --global | Push from '~/.workgraph/agency/' ...
  Line 2050: wg evolve apply .workgraph/agency/synthesis-result.json
  Line 2314: --delete-dirs | Also delete agent work directories ('.workgraph/agents/<id>/')
  Line 2395: PATH — Path to the peer project (containing '.workgraph/')
  Line 2468: --socket <PATH> | Unix socket path (default: '.workgraph/service/daemon.sock')
  Line 2994: --attachment <ATTACHMENT> | Attach a file (copied to '.workgraph/attachments/')
  Line 3080: --global | Write to global config ('~/.workgraph/config.toml')
  Line 3183: --value <VALUE> | Store key value directly (written to '~/.workgraph/keys/...')
  Line 3184: --global | Apply to global config ('~/.workgraph/config.toml')
  Line 3459: Creates '.workgraph/' directory with 'graph.jsonl'
  Line 3464: # Creates .workgraph/ directory ready for task management
  Line 3570: ... agent records from '.workgraph/service/registry.json'

wg agent-guide output:
  Line 492: # Or in .workgraph/config.toml under [dispatcher]: model = ...

Plus likely additional refs in:

  • README.md
  • CLAUDE.md (workgraph repo)
  • SKILL.md / installable skill files
  • Other docs/*.md files
  • src/commands/quickstart.rs (the bundled quickstart text)
  • src/commands/agent_guide.rs (the bundled agent-guide text)

Scope

Hard rename per user's skip-back-compat preference

Replace all .workgraph/ and ~/.workgraph/ references with .wg/ and ~/.wg/ respectively. NOT a deprecation window — a full sweep. Single user, hard cut.

EXCEPT: legitimate references to the OLD path in:

  • Migration / back-compat code (where the binary itself recognizes both for loading existing-but-not-yet-migrated configs)
  • Historical commit messages / release notes
  • One-line CHANGELOG entry noting the rename happened

Verify with fresh init

wg init (any route) creates the project directory at .wg/ (already does this — verified). Confirm zero .workgraph references in the generated config or directory structure.

Docs sweep

  • docs/COMMANDS.md (15+ refs identified)
  • wg agent-guide bundled text (1 ref identified)
  • Plus comprehensive grep across all .md files in docs/, README.md, CLAUDE.md, SKILL.md (if exists), etc.
  • Also grep src/commands/quickstart.rs and src/commands/agent_guide.rs source for include_str! payloads

Cause analysis

This bug should have been caught by the doc-sync run on 2026-04-29. It wasn't. The audit-terminology-consistency task focused on canonical names (nex: vs local:, dispatcher vs coordinator) but didn't enumerate path references. Worth amending the doc-sync function template (.wg/functions/doc-sync.yaml) to include path references in audit-terminology-consistency's scope: 'also flag every reference to .workgraph/ and ~/.workgraph/ as stale; canonical is .wg/ and ~/.wg/.'

Validation

  • grep across all agent-visible docs (docs/, README, CLAUDE.md, SKILL.md, agent-guide source, quickstart source) returns ZERO .workgraph/ references outside legitimate back-compat / migration / changelog mentions
  • wg agent-guide output: zero stale refs
  • wg quickstart output: zero stale refs
  • Live smoke: spawn an evaluator on a task in any project; verify the agent looks at .wg/output/<task>/ not .workgraph/output/...
  • Doc-sync function template (.wg/functions/doc-sync.yaml) updated to include path references in audit-terminology-consistency
  • cargo build + cargo test pass
  • cargo install --path . was run before claiming done

Process note

The autohaiku agent's wrong-path lookup caused a real false-negative evaluation (graded 0.00 on a task that may have had work to evaluate). This kind of bug — agent inferring the wrong filesystem layout from stale docs — is invisible until it bites. The fix is mechanical, but the root cause is doc drift that a more thorough audit-terminology-consistency would have caught.

Depends on

Required by

Log