← graph

sweep-purge-stale

Sweep: purge stale .workgraph references everywhere — replace with .wg, preserve back-compat layer

Metadata

Statusdone
Assignedagent-1383
Agent identityf51439356729d112a6c404803d88015d5b44832c6c584c62b96732b63c2b0c7e
Created2026-05-01T18:50:55.096330728+00:00
Started2026-05-01T19:25:24.512702883+00:00
Completed2026-05-01T19:43:37.735468149+00:00
Tagspriority-high,fix,paths,sweep,migration, eval-scheduled
Tokens6943425 in / 10153 out
Eval score0.69
└ blocking impact0.80
└ completeness0.65
└ constraint fidelity0.85
└ coordination overhead0.65
└ correctness0.70
└ downstream usability0.70
└ efficiency0.75
└ intent fidelity0.68
└ style adherence0.70

Description

Description

fix-replace-stale (commit 785bc5a32) handled docs but missed the broader codebase. fix-dir-flag was filed for the clap --dir default. Expanding to a comprehensive sweep — there are 1614 .workgraph matches across src/ (978), tests/ (513), docs/ (123). Most should become .wg, some are legitimate legacy references that MUST stay.

User direct quote 2026-05-01: 'can we tell it to find all cases of .workgraph and purge them? for .wg instead?'

Categorize each match before replacing

For each .workgraph reference, classify:

REPLACE with .wg

  • String literals in clap default_value annotations
  • Hardcoded path constructions in source (e.g., format!(".workgraph/output/{}"))
  • Test fixtures / setup code that creates the canonical project layout
  • Examples in doctests, README snippets, error messages
  • Doc comments showing canonical usage (/// Stores config in .workgraph/config.toml)

PRESERVE (legitimate legacy references)

  • The resolver in src/dispatch/discovery.rs (or wherever) that walks .wg → .workgraph for back-compat
  • Migration code that recognizes legacy projects (wg migrate config, etc.)
  • Tests that specifically exercise the legacy path
  • Glossary / changelog entries documenting the rename
  • Comments explaining the back-compat layer

EITHER preserve AND add a comment, OR replace

  • The grey area: code that USED to be canonical but now is just back-compat. If the comment explains 'legacy', keep. If it's an unmarked vestige, replace.

Approach (don't blanket sed)

  1. grep -rn ".workgraph" src/ tests/ docs/ > /tmp/workgraph-refs.txt
  2. For each match, classify per the categories above
  3. Apply changes in batches: clap defaults first (few, mechanical), then hardcoded paths, then comments
  4. Re-run the grep after each batch to verify the count is dropping in the right direction (no false positives)
  5. Final state: only matches in the documented exceptions remain (resolver, migration, glossary, tests-of-legacy-path)

Specific known stale references to address

  • -d, --dir <PATH> clap default: change to .wg OR remove default entirely (let resolver own discovery)
  • src/commands/quickstart.rs (or include_str! source) line 7: 'wg init # Create a .workgraph directory'
  • src/commands/quickstart.rs line 492: '# Or in .workgraph/config.toml under [dispatcher]'
  • docs/COMMANDS.md residual refs (15 found earlier — re-verify post-fix-replace-stale)

Help text especially

wg --help output, wg <subcommand> --help output, error messages — all of these are user-facing and should be self-consistently .wg for canonical usage. Run a sweep that captures every -h / --help output of every command and re-greps for .workgraph. Anything found at this level is high-priority since it directly misleads new users / agents.

Update the doc-sync function template

While at it, amend .wg/functions/doc-sync.yaml so future doc-sync runs include:

  • src/**/*.rs grep for path references
  • src/cli.rs / wherever clap annotations live
  • All #[arg(...)] and #[command(...)] attributes inspected for stale defaults
  • wg <subcommand> --help output for every subcommand re-greped

This makes the audit-terminology-consistency template structurally aware of clap-annotated source — closing the recurring gap.

Validation

  • Categorized list of all 1614 matches in task log: REPLACE, PRESERVE, GREY-AREA-resolved
  • After sweep: grep -rn '.workgraph' src/ tests/ docs/ returns ONLY the documented exceptions (back-compat resolver, migration, glossary, legacy-path tests)
  • wg --help shows no '.workgraph' references
  • wg init --help shows '.wg' as canonical, mentions '.workgraph' only as 'legacy' in resolver-precedence text
  • Every wg <subcommand> --help output re-greped, no stale '.workgraph' as canonical
  • doc-sync function template updated to cover src/**.rs
  • Live smoke: wg init in tmpdir creates .wg/ (not .workgraph/), wg list in that dir works without --dir flag
  • Live smoke: existing project with .workgraph/ (legacy) still loadable via resolver — back-compat preserved
  • cargo build + cargo test pass
  • No regression of any tests that specifically exercise legacy-path handling
  • cargo install --path . was run before claiming done

Process note

This task is the structural fix for a recurring 'doc-sync missed clap-annotated strings' bug class. Two prior fixes (fix-replace-stale, fix-dir-flag-now-abandoned) targeted symptoms. This sweep + the doc-sync template amendment closes the class going forward.

Depends on

Required by

Log