Skip to content

feat(snapshot): portable FileTree candidate with ledger lineage - #1138

Merged
Birfy merged 3 commits into
mainfrom
feat/artifact-snapshot
Nov 17, 2026
Merged

Birfy merged 3 commits into
mainfrom
feat/artifact-snapshot

Conversation

@Birfy

@Birfy Birfy commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator

Summary

This is item 3 from the FlashRSI design review: a portable snapshot on the existing FileTree and ledger, not a second store and not a new algorithm×harness×benchmark layer.

A snapshot is the complete candidate (editable files plus frozen context) plus the lineage the ledger already has: id is {artifact_id}@v{version}, parent is the previous version, root is {artifact_id}@v1. Algorithms still edit only the declared scope; evaluation and restore use the whole tree.

New surface:

  • Library: ArtifactSnapshot, evaluate_snapshot, evaluate_snapshot_spec, read_artifact_lineage
  • CLI: agentdescent snapshot export|show|eval|apply
  • Docs: docs/snapshot.md (README was not rewritten)

snapshot eval scores a frozen snapshot on a destination spec's tasks and scorer. The spec's target is ignored; its evolve knobs do not start a search. Kind must match. Host selection stays the existing agent/runner path on that destination spec. kind: plugin is still the plugin tree, not “run this snapshot inside Claude Code.”

evolve(test_frac=…) defaults and the silent reflect=agent default are unchanged.

This is a separate PR from the seed-consistency fix in #1137; the two do not share code.

Tests

  • tests/test_snapshot.py: frozen files are in the snapshot even if omitted from an editable-only state; JSON round-trip keeps lineage; lineage is read from the existing ledger (v3/v2/v1, distinct commits); readonly eval does not call evolve; dest-spec eval uses dest tasks and rejects a kind mismatch; a plugin snapshot is the plugin tree.
  • tests/test_snapshot_cli.py: show / export / eval / apply on a snapshot file, with evolve patched to fail if search starts.

Checklist

  • Changelog fragment will be added once this PR has a number
  • No new dependencies
  • No Cursor Cloud Coding Sessions
  • MCP Path A tools were left unchanged; the new verb is library + CLI. MCP parity can be a follow-up if we want it on the default tool list.

A snapshot is the complete agent context — editable files plus frozen
context — together with the id/parent/root the ledger already stores.
Capture it from a FileTree, a live ledger, or a finished run; score it
read-only on another compatible dataset; restore it with the existing
apply backup path. Algorithms still edit only the declared scope.
Plugin kind remains the plugin tree, and host selection is unchanged.
@Birfy

Birfy commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator Author

Self-review (Birfy)

Tip SHA: 8496079
Ran:

  • python3 .github/scripts/risk_gate.py --repo ThinkFlowLab/agentdescent --pr 1138 → T3 (size 953 lines / 12 files > T2 cap; docs/api.md generated and not counted)
  • pytest -q tests/test_snapshot.py tests/test_snapshot_cli.py tests/test_cli_help_hides_internal_run.py tests/test_ledger.py tests/test_changelog_fragments.py at this tip → 77 passed
  • python -m tools.changelog_fragments check → 64 changelog fragment(s) OK
  • python -m tools.gen_api_docs --check → docs/api.md is up to date
    Not run:
  • Full offline suite locally — CI is running the 3.9–3.13 matrix at this tip
  • mkdocs build --strict — docs pages were added; CI docs/site checks will cover this
  • Ark real-model run — no model path changed; tests stub/patch evolve and use the echo agent
  • MCP Path A tool for snapshot — library + CLI only in this PR; Path A tool count is unchanged
    Findings:
  • none that block. MCP parity for the new verb is a follow-up, not part of this change.
    Verdict: PASS

@Birfy
Birfy enabled auto-merge (squash) November 16, 2026 23:59
agentdescent/snapshot.py overwrote the package-level snapshot()
callable imported from evidence, so `from agentdescent import snapshot`
returned the module and self-improve tests raised TypeError. Rename the
new module to artifact_snapshot; ArtifactSnapshot and the `snapshot`
CLI stay the same.
@Birfy

Birfy commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator Author

Self-review (Birfy)

Tip SHA: 374017d
Ran:

  • python3 .github/scripts/risk_gate.py --repo ThinkFlowLab/agentdescent --pr 1138 → T3 (size 959 lines / 13 files > T2 cap; docs/api.md generated and not counted)
  • pytest -q tests/test_self_improve.py tests/test_snapshot.py tests/test_snapshot_cli.py tests/test_api_reference.py tests/test_changelog_fragments.py at this tip → 96 passed (14 self-improve including a new regression test that agentdescent.snapshot stays the evidence callable after importing ArtifactSnapshot, 7 snapshot, 1 snapshot CLI, 29 API reference, 45 changelog fragments)
  • python -m tools.changelog_fragments check → 64 changelog fragment(s) OK
  • python -m tools.gen_api_docs --check → docs/api.md is up to date; ### snapshot is again the evidence function, not the artifact-snapshot module docstring
    Findings:
  • The CI TypeError was a name clash: from .snapshot import … in __init__.py rebound agentdescent.snapshot from evidence.snapshot to the new module, so from agentdescent import snapshot was not callable. The module is now artifact_snapshot; ArtifactSnapshot and the snapshot CLI are unchanged. Existing changelog fragment kept (same PR story).
  • none that block.
    Verdict: PASS

@github-actions github-actions Bot added the risk:T3 Risk tier T3 (core loop, release, process; needs Danyang's click), set by the controller label Nov 17, 2026
@Birfy
Birfy merged commit fcebbdf into main Nov 17, 2026
9 of 10 checks passed
@Birfy
Birfy deleted the feat/artifact-snapshot branch November 17, 2026 02:03
Birfy added a commit that referenced this pull request Nov 17, 2026
## Summary

`#1138` made a snapshot the complete candidate, and for a text run that
candidate is `rendered`. `snapshot eval` already scores that text, but
`snapshot apply` materialised `files` (the strategy's internal rule
store) into a temp directory and handed it to `apply_from_payload`'s
tree path. A user who named a file got a directory of hash-named rule
files, and an empty-rules snapshot reported a no-op instead of writing
the seed prompt.

`cmd_snapshot_apply` now writes `snap.render()` to a temp file when
`kind == \"text\"` and passes that file to `apply_from_payload`, so the
text plan, `.bak-N` backup, no-op detection, and parent creation apply.
A directory `--to` is refused with an error naming FILE. Tree-kind
snapshots keep the materialise path.

Closes #1149.

## Tests

-
`tests/test_snapshot_cli.py::test_snapshot_show_export_eval_and_apply`:
text fixture now pins `--to missing.txt` writes exactly `rendered`, a
second apply is `noop: true`, a directory `--to` is refused, and an
empty-rules snapshot writes the seed prompt. Tree assertions move to a
`skill_dir` snapshot.

## Checklist

- [x] Changelog fragment `changelog.d/1149-snapshot-apply-text.md`
- [x] No new dependencies
- [x] No Cursor Cloud Coding Sessions

## Verification at the tip

Tip SHA: 8e983aa

Ran:
- pytest -q tests/test_snapshot_cli.py tests/test_snapshot.py
tests/test_text_kind_dir_target.py
- python -m tools.changelog_fragments check
- the issue's offline repro now writes the rendered prompt to
`prompt.txt` (exit 0, `noop: false`)

Not run:
- full `pytest -q` — the CI test matrix is the line
- Ark real-model run — no model path changed
HugoXK added a commit that referenced this pull request Nov 18, 2026
Forward-merge after #1138/#1140/#1139/#1147/#1148/#1151/#1152 landed.
#1148 rewrites agentdescent/pilot.py, the file this branch patches; the
auto-merge keeps both the per-seed _next_actions branch and the
notes/strategy card addition, and the focused set is green at the
merge tree.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:T3 Risk tier T3 (core loop, release, process; needs Danyang's click), set by the controller

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant