Skip to content

docs(cron): document startup quarantine recovery - #20751

Merged
bolichen97 merged 1 commit into
mainfrom
fix/17008-cron-quarantine-docs
Oct 21, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/17008-cron-quarantine-docs

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make cron quarantine recovery clear before an operator needs it.

The cron specification and the code comment do not fully say when startup moves an unreadable crons.json, where it goes, or how to restore it safely.

Why it matters

An operator needs the exact saved path and restore order to recover scheduled tasks without losing the quarantined bytes or overwriting tasks added later.

Not a goal

  • Change cron quarantine behavior.
  • Add a new recovery command or dashboard action.

What changed (motivation → approach → change)

An operator can read in the cron specification exactly when startup sets crons.json aside, where the copy goes, and how to put it back.

Quarantine runs only at gateway startup, when the JSON cannot be decoded or is not an object holding a jobs list; an object with no jobs key loads as an empty store. It renames the unchanged file into cron-history/quarantine, behind the file-tool fence and the sandbox mask. The dashboard notice and doctor name the copy and the restore order: repair it, run kirocrew stop, move it back, start again. Doctor warns that restoring replaces tasks added since.

The comment above cron_store_quarantine_copies in cron.py says the same, and both places name the two doctor store readers the facade test pins.

Backwards compatibility

Compatible: this changes documentation and comments only; runtime behavior and stored data are unchanged.

Removes nothing: no code path, data, key, or public function is removed.

Tests

No test is added or changed. Focused checks on the rebased head:

  • test/test_cron_store_quarantine.py, test/test_cron_load_malformed_entry.py, test/test_cli_doctor_refactor_facade.py, test/test_cron_refactor_contract.py, test/test_cron_service_bindings.py: 714 passed.
  • scripts/docs_lint.py --test, scripts/docs-lint.sh, check_comment_history.py, check_brand_name.py, check_feature_map.py: passed.
  • flake8, isort, black, mypy on src/kiro_crew/cron.py, and git diff --check: passed.

Manual verification

N/A — the focused tests and documentation checks cover this comment-only and specification-only change.

Screenshots / video

N/A — no user interface changes.

Related Issues

Closes #17008

Pattern harvest

Not generalizable: this fills one deferred documentation gap for an existing recovery path and does not change product behavior.

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.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 5c2085e542060c25225f85f8a9411406abcbe73b touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 5c2085e542060c25225f85f8a9411406abcbe73b — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The change only touches documentation and a comment, it changes no behaviour, removes nothing and adds no user-visible surface.

[DESIGN-REVIEWED] 5c2085e

Description read

[DESCRIPTION-READ] 0085570a429d7d8f7b3f3f90cdc2968296fb7d8d46036c5fb1bb4210316164b3

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 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 5c2085e542060c25225f85f8a9411406abcbe73b — 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 does not.

First-Principles-Verdict: PASS

Nothing blocks: this changes docs and comments only, it closes #17008, and every item describes recovery behaviour that already exists.

What this change ships

Inventory (4 items) — 4 justified

Intent: let an operator see when gateway startup sets aside an unreadable cron store, where the copy goes, and how to restore it safely. FIX (documentation gap, #17008).

  1. The cron spec now says quarantine also fires on a decoded non-object or a missing jobs list, and that an object with no jobs key loads empty — justified
  2. The cron spec states the restore order and doctor's warning that restoring replaces newer tasks — justified
  3. The spec's cron.py facade paragraph names the quarantine lister as the third store reader for doctor — justified
  4. The cron.py comment above cron_store_quarantine_copies is rewritten to match the spec — justified

[FIRST-PRINCIPLES-REVIEWED] 5c2085e

Description read

[DESCRIPTION-READ] 09e26408c1272c6ba7317691028a97fa83cb84dd6ac95d962b8012a047b7a8a1

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 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 5c2085e542060c25225f85f8a9411406abcbe73b — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5c2085e

Verdict parsed from the review's SHA-scoped output markers for commit 5c2085e542060c25225f85f8a9411406abcbe73b.

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

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 5c2085e542060c25225f85f8a9411406abcbe73b and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5c2085e

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

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 15, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/security.md, src/kiro_crew/hidden_leaf_staging.py (same directories) since this head went green (213339f -> b413800); CI re-running.

@iamwhatever
iamwhatever force-pushed the fix/17008-cron-quarantine-docs branch from 4826593 to fc4ce9f Compare October 15, 2026 09:52
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/app-kit-platform.md (same directory) since this head went green (b413800 -> dfc37de); CI re-running.

@iamwhatever
iamwhatever force-pushed the fix/17008-cron-quarantine-docs branch from fc4ce9f to a71e52d Compare October 15, 2026 10:41
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 15, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Status note: the diff is docs/comment only and every completed check is green. GPT 6.1 Review computed a verdict for a71e52d but could not publish it ("API rate limit exceeded for installation", run 38722064694; the verdict is kept in that run's withheld-verdict artifact). The same lane reported no findings on 4826593, which has the identical diff (range-diff equal). Opus, Design and First Principles: no findings / PASS. Handing over: rerun that job in a quiet API window (rebasing first if main moved), then maintainer review. No auto-merge armed.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 15, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased onto main 88914fd to clear the merge conflict (main rewrote the CronService paragraph; kept main's text and re-added only the third-reader clause). Re-checked every doc claim against the moved code (cron_service/service/, gateway_runtime/cron_fire.py). Local Opus review found two wording gaps in this diff, both fixed: the spec now credits only doctor with the "replaces tasks added since" warning, and the cron.py comment no longer says "exact copies". CI re-running.

@iamwhatever
iamwhatever force-pushed the fix/17008-cron-quarantine-docs branch from a71e52d to 9e3d891 Compare October 19, 2026 16:48
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 19, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • punchline: doctor prints the restore-overwrite warning

rebutted: the spec sentence matches doctor output. src/kiro_crew/doctor_checks/workload.py:379-380 (_doctor_cron_quarantine) prints "then start the gateway. That replaces any task added since."
The dashboard notice (gateway_runtime/cron_fire.py:853-866) gives no such warning, which is why the spec now credits only doctor with it.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Red checks on 9e3d891 are main's, not this docs-only diff: Harness Parity Gate (x-capture gate), Await Fast Gate and Coverage Gate fail the same way on main 88914fd (Fast Gate run 39285437059, CI run 39285437187). Fixes in flight: #22178, #22186. Waiting for them; no patch here.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 19, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased onto main 5f803ab, which carries the red-main fix #22178 (88914fd -> 5f803ab; range-diff identical). Re-ran 714 focused tests, harness-parity, docs lint, flake8: green. Doc claims re-checked against current code. CI re-running.

@iamwhatever
iamwhatever force-pushed the fix/17008-cron-quarantine-docs branch from 9e3d891 to 5c2085e Compare October 21, 2026 07:12
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 21, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Review-ready on head 5c2085e (one commit on main 5f803ab, which includes red-main fix #22178).

  • PR Readiness: passed (readiness: passed); 87 checks pass, 0 fail.
  • GPT and Opus: no findings on this head. Design and First Principles: PASS ("nothing blocks").
  • Mergeable, no unresolved threads, Closes #17008.
  • Change: docs and one comment only, no behaviour change. 714 focused tests pass locally.
  • Note: main has moved 19 commits since, in same-directory files only. None edits a file this PR touches, and we chose not to rebase again.

Needs one maintainer approval. No auto-merge armed.

@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 on 5c2085e. Spec text and one code comment only: when startup quarantines crons.json, where the copy goes, and the restore order. No behaviour change.

@bolichen97
bolichen97 merged commit 46beabf into main Oct 21, 2026
104 checks passed
@bolichen97
bolichen97 deleted the fix/17008-cron-quarantine-docs branch October 21, 2026 13:29
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 21, 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.

docs(cron): describe the startup quarantine of an unparseable crons.json in the cron spec

2 participants