Skip to content

feat(snapshot): add opt-in --strict exit 3 for an incomplete bundle - #17667

Merged
bolichen97 merged 1 commit into
mainfrom
fix/snapshot-strict-11700
Oct 7, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/snapshot-strict-11700

Conversation

@buluoray

@buluoray buluoray commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An unattended caller of kirocrew snapshot can ask the command to tell it, by exit status, that the bundle it wrote is incomplete.

Today kirocrew snapshot exits 0 after writing a bundle that omits entries it was asked to carry (unreadable_entry, vanished, ...). The omission is recorded in MANIFEST.json skipped[] and printed as human-readable ⚠️ lines on stdout, and --keep holds the prune. A cron backup or wrapper script still has no cheap signal: it must either grep the console text or re-implement the symlink/not_regular screening that pinned_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

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 --strict flag (shape 3). A new default exit code (shape 1) would make the in-tree AWS Control backup (backup.py, rc != 0 raises before upload) stop uploading bundles that are written and restorable. A stdout status line (shape 2) still makes callers parse output. --strict gives 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_main returns 3 when --strict was passed and the existing omitted list (built with pinned_fs.omits_wanted_data) is non-empty. Reason codes are not re-enumerated. The bundle is kept and the prune is still held.
  • --strict is added to both the standalone parser and the kirocrew snapshot parser in cli.py.
  • docs/system-specs/modules/cli.md, src/kiro_crew/docs/snapshot-and-restore.md and the kirocrew-commands built-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 --strict every 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, class TestABundleWithOmissionsDoesNotPrune:

  • test_strict_exits_3_for_an_incomplete_bundle: denied entry plus --strict --keep 1 returns 3, both bundles remain, and the --strict: exiting 3 line is printed.
  • test_without_strict_an_incomplete_bundle_still_exits_0: pins the unchanged default contract.
  • test_strict_exits_0_for_a_complete_bundle: --strict does not fail an ordinary run.

Mutation check: replacing the return EXIT_INCOMPLETE with pass reddens the first test; changing the condition from omitted and strict to omitted or strict reddens two. Ran pytest -n0 on 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_unchanged gains the --strict row.
  • test/test_snapshot_refactor_ownership.py declares EXIT_INCOMPLETE as a kiro_crew.snapshot name.

Manual verification

N/A for Linux: unit coverage drives snapshot_main end to end with a denied entry. Not verified on Windows or macOS. The kirocrew snapshot wiring was checked by reading cli.py (snapshot_main(parsed=args); strict is read with getattr). I did not render kirocrew snapshot --help.

Related Issues

Refs #11700. This draft covers decision (a), the signal contract; decision (b), the --keep ceiling, is still open on the issue. Related: #11418, #11499.

Decision for the owner

The decision is what signal kirocrew snapshot gives 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 --strict that exits 3, because it reuses omits_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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@buluoray
buluoray force-pushed the fix/snapshot-strict-11700 branch from e948d99 to 70b029b Compare October 7, 2026 09:01
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 7, 2026
@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 88e1108fdd68334a747649dfa859817e8ca1d63f — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

No in-tree caller passes --strict (0 found; backup.py:323 deliberately doesn't), so check that #11700's unattended-caller need is real.

What this change ships

Inventory (5 items) — 5 justified

Intent: 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).

  1. kirocrew snapshot --strict exits 3 when the written bundle omits data it was asked to carry. It reuses the existing omitted list built by pinned_fs.omits_wanted_data. — justified
  2. Without --strict, an incomplete bundle still exits 0, so the default is unchanged. — justified
  3. A new console line, ⚠️ --strict: exiting 3 …, is printed under --strict. — justified
  4. A new public constant, snapshot.EXIT_INCOMPLETE = 3. — justified
  5. The flag and the exit statuses are documented in the cli.md spec, snapshot-and-restore.md and the kirocrew-commands skill. — justified

[FIRST-PRINCIPLES-REVIEWED] 88e1108

Description read

[DESCRIPTION-READ] eb59fbd6caa7bc7f676c67e0bb80059d0efc0da8c3f70336073854dd4de5c446

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 88e1108fdd68334a747649dfa859817e8ca1d63f — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Before merge, check by hand that kirocrew snapshot --strict --help shows the flag; the PR says the help output was never rendered and the cli.py wiring was only read.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 88e1108fdd68334a747649dfa859817e8ca1d63f — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 88e1108

Verdict parsed from the review's SHA-scoped output markers for commit 88e1108fdd68334a747649dfa859817e8ca1d63f.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 88e1108fdd68334a747649dfa859817e8ca1d63f: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 88e1108fdd68334a747649dfa859817e8ca1d63f and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 88e1108

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 88e1108fdd68334a747649dfa859817e8ca1d63f: <one-sentence reason>

@buluoray
buluoray force-pushed the fix/snapshot-strict-11700 branch from 70b029b to 88e1108 Compare October 7, 2026 09:22
@buluoray
buluoray marked this pull request as ready for review October 7, 2026 18:20
@buluoray
buluoray requested a review from a team as a code owner October 7, 2026 18:20
@buluoray
buluoray requested a review from dodgeblaster October 7, 2026 18:20
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 7, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

The code is correct. --strict reuses the same omitted predicate that holds the prune, so callers never re-classify skip reasons. The default exit code is unchanged, so the AWS Control backup is not affected. Three tests pin exit 3, the default exit 0, and a clean --strict run. I'm holding because this sets a public CLI exit-code contract, and the PR's own "Decision for the owner" section leaves the choice between three shapes from #11700 open. No in-tree caller uses --strict yet, so a maintainer should confirm both the shape and the value 3 before merge. Nobody has rendered kirocrew snapshot --help yet either.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

@bolichen97
bolichen97 merged commit 293038e into main Oct 7, 2026
107 of 114 checks passed
@bolichen97
bolichen97 deleted the fix/snapshot-strict-11700 branch October 7, 2026 22:52
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 7, 2026
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.

3 participants