Skip to content

docs: record a kiro-wide uninstaller wipe as an accepted risk - #33699

Merged
bolichen97 merged 1 commit into
mainfrom
fix/355-uninstaller-accepted-risk
Nov 11, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/355-uninstaller-accepted-risk

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The data-home spec and the install guide say truthfully that a Kiro-family uninstaller removing all of ~/.kiro/ is a documented accepted risk, not a release gate, and tell users how to keep their data and snapshots out of its reach.

The data-home spec calls UNINSTALLER-EXCLUDE-CREW a release gate: the product owner MUST confirm, for every release, that Kiro-family uninstallers skip ~/.kiro/crew or prompt first, and the install guide calls that sign-off release-blocking. Releases have shipped the data home under ~/.kiro/ since v0.1.1 without it, no release step reads it, and nothing in this repository can constrain another product's uninstaller.

Why it matters

A spec that names a release gate nobody runs reads like a protection users have. The exposure itself (a ~/.kiro/-wide removal deleting the data home) is the same either way. What users can act on is the protections Kiro Crew owns, and today the install guide does not tell them to keep the data home or their snapshots outside ~/.kiro/.

Not a goal

  • Changing any code, config default, flag or test.
  • Saying what another product's uninstaller deletes.
  • Adding a new protection (a backup job, an uninstall hook, a prompt).
  • Changing the spec's request that any Kiro-family uninstaller excludes ~/.kiro/crew or prompts.

What changed (motivation → approach → change)

A maintainer ruled on #355 that the gate becomes a documented accepted risk, so the two docs that called it release-blocking now say what is true and point users at the protections that exist.

Where Before After
docs/system-specs/modules/config.md, Data Home Location "Release gate (UNINSTALLER-EXCLUDE-CREW)": the owner MUST sign off every release; tracked as release-blocking "Accepted risk (UNINSTALLER-EXCLUDE-CREW)": the remaining risk, the four protections Kiro Crew owns, and "reopen #355" if an uninstaller is found to remove ~/.kiro/ wholesale
docs/guides/install.md, Windows NSIS paragraph "That release-blocking cross-product sign-off is tracked in issue #355" the accepted-risk sentence, plus: set KIROCREW_HOME and snapshot_dir outside ~/.kiro/
docs/decisions/ nothing an entry recording the ruling, and its index row

The four protections are the repository's own uninstall paths (they keep the data home), the ~/.kirocrew.breadcrumb pointer, KIROCREW_HOME, and snapshot_dir outside ~/.kiro/. The name UNINSTALLER-EXCLUDE-CREW stays so a search still finds it. The install guide also says that KIROCREW_HOME starts a new data home rather than moving one, that the crewmate agent files in ~/.kiro/mates do not move with it, and that a snapshot is not a full backup.

Backwards compatibility

Compatible: docs only; no code, config, flag or test changes.

Removes nothing: no check or code path goes away; git grep -n 'UNINSTALLER-EXCLUDE\|issues/355' origin/main finds only the two doc spots rewritten here, so no release step, script, skill or test read the old gate.

Tests

No test: docs only. scripts/docs_lint.py passes (the new links and the #data-home-location and #removing-user-data anchors resolve), and scripts/check_decisions_history.py passes (one new entry, no shipped entry touched).

Manual verification

N/A — docs only. The facts the new text states were checked against the code: snapshot.py _default_snapshot_dir falls back to config_dir() / "snapshots"; config/paths.py config_dir() only creates a KIROCREW_HOME folder and copies nothing into it; v0.1.1 is the first stable tag containing the data-home move.

Related Issues

Closes #355

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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 9, 2026 05:01
@bolichen97
bolichen97 requested a review from Zedmor November 9, 2026 05:01
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 877c2a296518e3496d32fc4c8ff4c6a9623b0889 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 commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 877c2a296518e3496d32fc4c8ff4c6a9623b0889 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Docs-only change recording a maintainer ruling. It takes nothing away that any code, release step or test reads.

[DESIGN-REVIEWED] 877c2a2

Description read

[DESCRIPTION-READ] 43724e276f18eea1fc8a2794fb7f03d17957bbbe93c8f07a2528057fa0a241c2

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 Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 877c2a296518e3496d32fc4c8ff4c6a9623b0889 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 877c2a2

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 877c2a296518e3496d32fc4c8ff4c6a9623b0889 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 877c2a296518e3496d32fc4c8ff4c6a9623b0889 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 877c2a2

Verdict parsed from the review's SHA-scoped output markers for commit 877c2a296518e3496d32fc4c8ff4c6a9623b0889.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 877c2a296518e3496d32fc4c8ff4c6a9623b0889 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 9, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 9, 2026 05:14
buluoray
buluoray previously approved these changes Nov 9, 2026

@buluoray buluoray 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. Docs only: the UNINSTALLER-EXCLUDE-CREW "release gate" is rewritten as a documented accepted risk, following the maintainer's own decision on #355 (docs/system-specs/modules/config.md:374-392, docs/guides/install.md:1563-1574, docs/decisions/2026-11-09-a-kiro-wide-uninstaller-wipe-is-an-accepted-risk.md:1-30). Every factual claim checks out against source.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 9, 2026
@bolichen97
bolichen97 force-pushed the fix/355-uninstaller-accepted-risk branch from 24a3b7a to 31f5e72 Compare November 10, 2026 00:05
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/decisions/README.md, docs/guides/install.md and docs/system-specs/modules/config.md since this head went green (2caa69b -> fd5d9ef); CI re-running.

GitHub reported a merge conflict in docs/decisions/README.md: main added an index row at the same spot as this PR's row, and both rows are kept. The Static Ratchet Gate and Coverage Gate reds on the previous head were red on main at the time and main's Fast Gate is green now. The change itself is the same as the approved head (git range-diff shows only context lines moved).

[operator: bolichen97]

@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 10, 2026
@bolichen97
bolichen97 force-pushed the fix/355-uninstaller-accepted-risk branch from 31f5e72 to 2e6be0a Compare November 10, 2026 16:42
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/decisions/README.md, docs/guides/install.md and docs/system-specs/modules/config.md since this head went green (fd5d9ef -> 0396be4); CI re-running.

GitHub reported a merge conflict in docs/decisions/README.md: main added an index row at the same spot as this PR's row, and both rows are kept. The reds on the previous head were GitHub API rate-limit errors inside the jobs (API rate limit exceeded for installation), not findings. The change itself is the same as the previous head (git range-diff shows only context lines moved).

[operator: bolichen97]

@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 10, 2026

@buluoray buluoray 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.

Approve on 2e6be0a. Since 31f5e72 the author only rebased the branch onto main 0396be4; the four-file docs diff is the same apart from the README index row's surrounding context. The accepted-risk decision is recorded by maintainer Bolin Chen and matches his #355 comment. Every source claim still holds at the new head. Decisive lines: docs/decisions/2026-11-09-a-kiro-wide-uninstaller-wipe-is-an-accepted-risk.md:3, docs/system-specs/modules/config.md:374, docs/guides/install.md:1588, src/kiro_crew/snapshot.py:254, src/kiro_crew/config/paths.py:781, src/kiro_crew/config/paths.py:1351

@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 Nov 10, 2026
The data-home spec called UNINSTALLER-EXCLUDE-CREW a release gate that
the product owner must sign off for every release, and the install
guide called it release-blocking. Releases have shipped the data home
under ~/.kiro/ since v0.1.1 without that sign-off, and nothing in this
repository can constrain another product's uninstaller.

Restate it as a documented accepted risk, list the protections Kiro
Crew owns (its own uninstall paths keep the data home, the breadcrumb,
KIROCREW_HOME, snapshot_dir outside ~/.kiro/), tell users in the
install guide how to keep the data home and snapshots out of reach and
that ~/.kiro/mates does not move with KIROCREW_HOME, and record the
maintainer decision in docs/decisions.

Closes #355
@bolichen97
bolichen97 force-pushed the fix/355-uninstaller-accepted-risk branch from 2e6be0a to 877c2a2 Compare November 11, 2026 06:02
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/decisions/README.md, docs/guides/install.md and docs/system-specs/modules/config.md since this head went green (0396be4 -> ea742a7); CI re-running.

The reds on the previous head were main's, not this PR's: the same Backend Tests node ids (test/test_session_markdown.py::test_a_condition_one_opener_is_closed_as_the_parser_reads_it[long-s] and the code-channel trust tests) failed on main at 096f6d9, and #34646 fixed them on main. This base carries that fix. The change itself is the same as the previous head (git range-diff shows only context lines moved).

[operator: bolichen97]

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 11, 2026
@bolichen97
bolichen97 merged commit 67e5628 into main Nov 11, 2026
98 of 106 checks passed
@bolichen97
bolichen97 deleted the fix/355-uninstaller-accepted-risk branch November 11, 2026 13:32
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 11, 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.

UNINSTALLER-EXCLUDE-CREW: uninstaller must exclude ~/.kiro/crew before first release with data under ~/.kiro/

2 participants