Dogfood operations

Start with status

Run the status command before analysis or recovery:

python -m src.cli dogfood status --db 'CPG_PATH' --review-dir 'REVIEW_DIR' --json

Pass --db 'CPG_PATH' explicitly to select the graph to check. Use the same path for status, analysis, and reports.

Inspect at least workflow_state, CPG freshness, read availability and recommended_next_action. A readable graph can still be stale. Use the freshness fields and recommended_next_action to decide whether to refresh the graph.

Analyze a commit range

The default base is HEAD~1:

python -m src.cli dogfood analyze --db 'CPG_PATH' --base-ref 'BASE_REF'

Use the exact comparison point needed by the review, for example a remote base branch. The report can include changed methods, complexity, the scope of a change’s impact, interface impact and other signals available in the current CPG. Check data availability for each metric: a missing value means that additional data is needed to calculate it.

Generate a quality report

python -m src.cli dogfood report --db 'CPG_PATH' --format markdown
python -m src.cli dogfood report --db 'CPG_PATH' --format json

The report uses the explicitly selected graph to analyze changes in the current checkout against HEAD~1. It describes changes in the last commit. For a full project audit, use the CPG audit guide. To save the report, 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 'CPG_PATH' --path 'DOC_PATH'

The default path is the current directory. The command finds numeric claims using supported patterns and compares them with CPG data. This helps detect discrepancies after project changes. Claim-validation errors return exit code 1.

Inspect the recent trend

python -m src.cli dogfood trend --db 'CPG_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 'CPG_PATH' --stories 'STORY_ID' --path 'STORIES_PATH.md' --output 'REPORT_PATH.md'

Replace STORY_ID with a story number, STORIES_PATH.md with a compatible story registry, and REPORT_PATH.md with the output location. Without --stories, the command evaluates the Done stories selected by the current implementation. --go-db 'GO_CPG_PATH' adds the supported cross-repo Go scope. This report is product traceability evidence only within its stated coverage; it does not close a task or story. The output file is Markdown with metadata, not JSON. The command can also project urgent findings; authorize that write before execution. Exit code 0 means the report was generated, not that all interfaces are covered: inspect each story result.

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.

The JSON orphans array lists each parameter, its location, problem type and severity. The summary object groups findings by type and severity, including errors, warnings and info. Review errors first, then warnings. Use each finding’s file path and line number to check the parameter against the source.

The exit code reflects the selected --level: 2 when errors are present, 1 for warnings, and 0 when neither is present. Informational findings remain in the report with exit code 0. Use --output to save the JSON report to a file; the command writes its save confirmation separately to stderr.

Maintain the graph database

python -m src.cli dogfood maintain-db --db 'CPG_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. Maintenance requires an accessible GoCPG service with maintenance RPC support. Inspect ok and message: unsuccessful maintenance exits with code 1.