Dogfood commands use CodeGraph’s own project graph and review traces to expose freshness, commit-analysis results and the next safe operator action. They are diagnostic and maintenance tools. Repository import, code commits, and release readiness use their own workflows and evidence.
Start with status
Run the status command before analysis or recovery:
python -m src.cli dogfood status --db PATH --review-dir <path> --json
--db PATH is required by the execution layer even though the generated
argument help does not label it as required. This fail-closed rule prevents a
command from borrowing a hidden active-project database.
Inspect at least workflow_state, CPG freshness, read availability and
recommended_next_action. A readable graph can still be stale. A successful
command only confirms that the status was calculated, not that the graph is
current.
Analyze a commit range
The default base is HEAD~1:
python -m src.cli dogfood analyze --db PATH --base-ref <git-ref>
Use the exact comparison point needed by the review, for example a remote base branch. The report can include changed methods, complexity, blast radius, interface impact and other signals available in the current CPG. Missing data must remain visible; do not treat an absent metric as zero.
Generate a quality report
python -m src.cli dogfood report --db PATH --format markdown
python -m src.cli dogfood report --db PATH --format json
The report describes the currently resolved project. For a durable artifact, redirect standard output to a caller-owned file. Record the Git revision and graph freshness alongside it.
Validate numeric documentation claims
python -m src.cli dogfood validate-claims --db PATH --path <file-or-directory>
The default path is the current directory. This check helps find quantitative claims that no longer agree with the graph. It does not validate prose, security promises or runtime behavior outside its supported claim patterns.
Inspect the recent trend
python -m src.cli dogfood trend --db PATH --commits 20
The default window is ten commits. Compare runs only when their project scope, graph construction and measurement rules are compatible.
Validate story interface coverage
python -m src.cli dogfood validate-stories --db PATH --stories 1231 --path docs/development/USER_STORIES.md --output <report.json>
Without --stories, the command evaluates the Done stories selected by the
current implementation. --go-db <go-cpg.duckdb> adds the supported cross-repo
Go scope. This report is product traceability evidence only within its stated
coverage; it does not close a story capsule.
Check configuration usage
python -m src.cli dogfood config-check --format json --level all --fix-suggestions
Use --config, --schema, --source and --output when the defaults do not
match the checkout. Fix suggestions are advisory. Review every proposed change
against the actual configuration contract.
Maintain the graph database
python -m src.cli dogfood maintain-db --db PATH --json
The command runs CHECKPOINT or VACUUM only when maintenance is due. Use
--force deliberately. Do not run it concurrently with an import or another
writer.
Continue the guided workflow
python -m src.cli dogfood continue --db PATH --review-dir <path> --json
continue reads the current state and performs the next supported safe step
when possible. The JSON response identifies the operation and resulting state.
When it cannot advance, return to status and follow recommended_next_action; resolve the
reported ownership, freshness or write-safety condition through the named workflow.
Command summary
| Task | Command |
|---|---|
| Current state | python -m src.cli dogfood status --db PATH |
| Commit analysis | python -m src.cli dogfood analyze --db PATH |
| Quality report | python -m src.cli dogfood report --db PATH |
| Documentation claims | python -m src.cli dogfood validate-claims --db PATH |
| Quality trend | python -m src.cli dogfood trend --db PATH |
| Story interfaces | python -m src.cli dogfood validate-stories --db PATH |
| Configuration usage | python -m src.cli dogfood config-check |
| Database maintenance | python -m src.cli dogfood maintain-db --db PATH |
| Guided next step | python -m src.cli dogfood continue --db PATH |
story-validate is a registered alias for validate-stories, but new scripts
should use the canonical name shown above.
Recovery sequence
- Run
python -m src.cli dogfood status --db PATH --json. - Confirm that the explicit CPG is the intended target.
- If the graph is stale or unavailable, use the project’s supported import or update workflow outside the dogfood command group.
- Re-run status and verify the changed freshness fields.
- Run the focused analysis, claims check or report.
- Preserve the output with its Git and CPG revision when it will be cited.
Do not delete a CPG as a first recovery step. A database lock can mean another writer is active; identify and coordinate with that owner before maintenance.
Maintained source
src/cli/dogfood_suite/dogfood_commands.py defines the registered subcommands,
parameters and guided state behavior. src/cli/dogfood_suite/dogfood_common.py
enforces the explicit database selection. Related analysis implementations
live under src/dogfooding/. Current CLI help and source are authoritative
when they differ from this guide.