Skip to content

docs: clarify resume trust boundary#2

Merged
Maleick merged 1 commit intomainfrom
codex/docs-resume-security
Apr 13, 2026
Merged

docs: clarify resume trust boundary#2
Maleick merged 1 commit intomainfrom
codex/docs-resume-security

Conversation

@Maleick
Copy link
Copy Markdown
Owner

@Maleick Maleick commented Apr 13, 2026

Summary

  • Clarify that --resume reads executable commands from the current invocation, not autoresearch-state.json.
  • Update the README, wiki Configuration/Safety pages, and architecture reference to keep the resume semantics consistent.

Verification

  • git diff --check
  • version consistency check
  • command frontmatter check
  • workflow cross-reference check

Copilot AI review requested due to automatic review settings April 13, 2026 20:29
@Maleick Maleick merged commit f1e63ee into main Apr 13, 2026
3 checks passed
@Maleick Maleick deleted the codex/docs-resume-security branch April 13, 2026 20:29
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Clarifies the trust boundary for /autoresearch --resume, ensuring docs consistently state that executable commands are sourced from the current invocation (not from autoresearch-state.json).

Changes:

  • Document that Verify: must be re-supplied on --resume and that state-file command fields are not executed.
  • Add/expand resume behavior notes in the wiki Configuration and Safety pages.
  • Update README and architecture docs to reflect the same resume semantics.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File Description
wiki/Safety.md Adds an explicit safety guarantee and non-guarantee around command sourcing on resume / tampered state files.
wiki/Configuration.md Updates --resume docs and adds a dedicated “Resume Behavior” section clarifying command execution semantics.
docs/ARCHITECTURE.md Updates state machine description to clarify command sourcing on resume and adds a note about command fields being record-only.
README.md Aligns safety/config/docs sections to state commands on resume come from the current invocation and Verify: is re-supplied.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

State is checkpointed to `autoresearch-state.json` after every phase. This enables `--resume` after crashes. On resume, executable commands come from the current invocation; the state file only restores non-executable loop metadata.

Schema fields: `run_id`, `schema_version`, `branch`, `iteration`, `max_iterations`, `best_metric`, `direction`, `goal`, `scope`, `verify_cmd`, `guard_cmd`, `start_time`, `duration_limit`, `discarded_descriptions`.
Schema fields: `run_id`, `schema_version`, `branch`, `iteration`, `max_iterations`, `best_metric`, `direction`, `goal`, `scope`, `verify_cmd`, `guard_cmd`, `start_time`, `duration_limit`, `discarded_descriptions`. `verify_cmd` and `guard_cmd` are record-only metadata and are not executed from the state file on resume.
Copy link

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The state file schema field list here appears inconsistent with the authoritative schema described in plugins/autoresearch/skills/autoresearch/references/state-management.md (e.g., that document uses previous_best/baseline/consecutive_*/last_phase_completed rather than best_metric/discarded_descriptions). To avoid confusing implementers/readers, update this field list to match the state-management reference (or explicitly label it as a non-exhaustive/illustrative subset).

Suggested change
Schema fields: `run_id`, `schema_version`, `branch`, `iteration`, `max_iterations`, `best_metric`, `direction`, `goal`, `scope`, `verify_cmd`, `guard_cmd`, `start_time`, `duration_limit`, `discarded_descriptions`. `verify_cmd` and `guard_cmd` are record-only metadata and are not executed from the state file on resume.
The authoritative state schema is defined in `plugins/autoresearch/skills/autoresearch/references/state-management.md`. At a high level, the checkpoint includes run identity, loop counters, branch/goal/scope metadata, metric-tracking state, phase progress, timing/limit information, and record-only command metadata such as `verify_cmd` and `guard_cmd`; these command fields are not executed from the state file on resume.

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants