Skip to main content
A scan checks disk before it calls the model, at three levels:
  • Agent level. An agent whose last run matches the current scope skips entirely. Its findings come from disk instead of a fresh call.
  • File level. Inside an agent that did not finish, each file resumes alone when its content and the recon brief match the copy on disk.
  • Finding level. The validate, score, and fix phases skip a finding that already carries a verdict, a score, or a fix. Live validation skips a finding that already has a live result.

​
What breaks resume

​
--source-id

Resume state is keyed to a source identity. By default, that identity is the absolute path of the scan root. That breaks the moment the codebase moves to a different path. A fresh checkout in a build job does this. So does a container mount that gets a new path each run. Pass --source-id <id> with a label you pick, and resume follows that label instead of the path. Use one id per codebase. Two codebases under the same id will read each other’s cached findings.

​
When to force a fresh pass

  • --rescan re-analyzes every file even when its content and the recon brief have not changed. Use it after an agent’s own template changes, since resume does not track that.
  • --re-recon re-runs recon and the precondition plan even when a cached brief still matches the project. Use it after the project’s stack changes enough that the old brief no longer fits. Also use it after an agent was wrongly skipped.
  • --revalidate-all and --rescore do the same for findings that already carry a verdict or a score.
  • agentgg fix --force and agentgg live-validate --force do the same for suggested fixes and live results.

​
Reports

A finished scan writes summary.md and one markdown file per finding under findings/, both inside --output. agentgg summary <dir> writes the same output later from files already on disk, with no calls to the model. This is what --no-summary defers to. See Commands for both.

​
summary.md

  • The scan root, start time, end time, and duration.
  • Files scanned and the total finding count.
  • The number of duplicates folded into a primary finding, if any.
  • Findings grouped by agent, by verdict, and by severity. The verdict counts include primary findings only.
  • A live validation table, when live validation ran.
  • Every finding, sorted by severity and then by score, with a link to its file.

​
One finding file

When live validation ran, the Validation line includes the live result. The ### Validation section keeps the validator’s own verdict, its reasoning, and the confirmed impact. Some sections appear only when they apply: When live validation reproduced or refuted a finding, a folder with the same name as the finding file holds its evidence.