Repository navigation
feat(snapshot): add opt-in --strict exit 3 for an incomplete bundle - #17667
Conversation
e948d99 to
70b029b
Compare
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS No in-tree caller passes What this change shipsInventory (5 items) — 5 justifiedIntent: let a cron job or wrapper script see from the exit code alone that a snapshot bundle is incomplete. This is an ADDITION (an opt-in flag that changes no default).
[FIRST-PRINCIPLES-REVIEWED] 88e1108 Description read[DESCRIPTION-READ] eb59fbd6caa7bc7f676c67e0bb80059d0efc0da8c3f70336073854dd4de5c446 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Before merge, check by hand that [DESIGN-REVIEWED] 88e1108 Description read[DESCRIPTION-READ] 040b6ad6793a1b58e7c525b20ee4c73cc9d5537329deba1140fb3c6d30b818ca That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
70b029b to
88e1108
Compare
|
The code is correct. |
bolichen97
left a comment
There was a problem hiding this comment.
Approving. An opt-in --strict with EXIT_INCOMPLETE = 3 is the least disruptive of the options in the issue, and it reuses the existing omitted check from pinned_fs.omits_wanted_data, so no reason codes are restated. cli.py passes the parsed args through snapshot_main(parsed=args), so the flag works from both entry points, and the docs, skill table and CLI contract move together.
Problem / Motivation
Goal: An unattended caller of
kirocrew snapshotcan ask the command to tell it, by exit status, that the bundle it wrote is incomplete.Today
kirocrew snapshotexits 0 after writing a bundle that omits entries it was asked to carry (unreadable_entry,vanished, ...). The omission is recorded inMANIFEST.jsonskipped[]and printed as human-readable⚠️lines on stdout, and--keepholds the prune. A cron backup or wrapper script still has no cheap signal: it must either grep the console text or re-implement thesymlink/not_regularscreening thatpinned_fs.omits_wanted_data()owns.Why it matters
A backup that silently lacks data is reported as a success to every scheduler and wrapper that checks the exit code. The operator finds out only when they need the missing file.
Not a goal
--strictexits exactly as before.keep+Nceiling on the bundles the not-pruning guard holds back, or treating a persistentvanisheddifferently fromunreadable_entry. Both were deferred to snapshot: signal an incomplete bundle to unattended callers #11700 from fix(snapshot): scope the size estimate and skip entries the process cannot read #11418 and stay open.--strict.What changed (motivation → approach → change)
Goal: give unattended callers a reliable completeness signal without breaking callers that treat non-zero as failure.
Approach: of the three shapes in the issue, an opt-in
--strictflag (shape 3). A new default exit code (shape 1) would make the in-tree AWS Control backup (backup.py,rc != 0raises before upload) stop uploading bundles that are written and restorable. A stdout status line (shape 2) still makes callers parse output.--strictgives an exit-code contract only to callers that ask for it.Change:
snapshot.py:EXIT_INCOMPLETE = 3. After the bundle is written and retention has run,snapshot_mainreturns 3 when--strictwas passed and the existingomittedlist (built withpinned_fs.omits_wanted_data) is non-empty. Reason codes are not re-enumerated. The bundle is kept and the prune is still held.--strictis added to both the standalone parser and thekirocrew snapshotparser incli.py.docs/system-specs/modules/cli.md,src/kiro_crew/docs/snapshot-and-restore.mdand thekirocrew-commandsbuilt-in skill document the flag and the exit statuses (0 written, 1 no usable bundle, 3 written but incomplete under--strict).Not a product-shape change: no default changes. The flag is additive.
Backwards compatibility
Compatible: without
--strictevery run exits exactly as on main; the flag is new and off by default.Removes nothing: the diff only adds a flag, a constant and an exit branch reached solely when the flag is passed.
Tests
test/test_snapshot_unreadable_entries.py, classTestABundleWithOmissionsDoesNotPrune:test_strict_exits_3_for_an_incomplete_bundle: denied entry plus--strict --keep 1returns 3, both bundles remain, and the--strict: exiting 3line is printed.test_without_strict_an_incomplete_bundle_still_exits_0: pins the unchanged default contract.test_strict_exits_0_for_a_complete_bundle:--strictdoes not fail an ordinary run.Mutation check: replacing the
return EXIT_INCOMPLETEwithpassreddens the first test; changing the condition fromomitted and stricttoomitted or strictreddens two. Ranpytest -n0on the three files below: 104 passed.Pinned contracts updated for the intended addition:
test/test_snapshot_refactor_contracts.py::test_the_snapshot_command_line_is_unchangedgains the--strictrow.test/test_snapshot_refactor_ownership.pydeclaresEXIT_INCOMPLETEas akiro_crew.snapshotname.Manual verification
N/A for Linux: unit coverage drives
snapshot_mainend to end with a denied entry. Not verified on Windows or macOS. Thekirocrew snapshotwiring was checked by readingcli.py(snapshot_main(parsed=args);strictis read withgetattr). I did not renderkirocrew snapshot --help.Related Issues
Refs #11700. This draft covers decision (a), the signal contract; decision (b), the
--keepceiling, is still open on the issue. Related: #11418, #11499.Decision for the owner
The decision is what signal
kirocrew snapshotgives an unattended caller when it writes a bundle that omits data it was asked to carry: a new default exit code, a stdout status line, or an opt-in--strict. This draft chose an opt-in--strictthat exits 3, because it reusesomits_wanted_data()and gives scripts a plain exit-code contract without breaking the AWS Control backup and other callers that treat any non-zero exit as failure, which a new default exit code would.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.