Skip to content

feat: skip heavy cli imports for bare --version - #8773

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
Arin016:feat/version-fast-path
Sep 13, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
Arin016:feat/version-fast-path

Conversation

@Arin016

@Arin016 Arin016 commented Sep 5, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Bare kirocrew --version pays ~250ms of module-scope imports it never uses (apps.builtins, cli_doctor -> aiohttp, the history -> sandbox/platform chain). Measured on a checkout at upstream main: python -m kiro_crew --version takes ~255ms while doing no work beyond printing a version string.

Why it matters

--version is the cheapest health/probe signal a CLI has: setup flows, installers, and scripts shell out to <tool> --version to detect executables. Paying a quarter-second of pure import overhead on every probe is waste, and every future top-level import added to cli.py would make --version slower still with no upper bound. The fast-path caps it near interpreter-startup cost permanently. If left undone nothing breaks, but the flag stays pointlessly slow.

What changed (motivation -> approach -> change)

  • Goal: answer bare --version without importing kiro_crew.cli heavy module scope.
  • Approach: two tiny argv guards (one per entry path) printing kirocrew <version> and exiting 0 — chosen over deferring more of cli.py top-level imports into functions, which would be a larger, riskier refactor for the same saving on this flag. Only the exact single-arg form fast-paths, because artifact show --version N reuses the flag name for an artifact-version int and must keep argparse semantics. Deliberately no cli.py module-scope guard: every desktop/frozen launcher routes through python -m kiro_crew (packaging/build-desktop.sh, website/electron/find-bin.js), and the only non-test importer of kiro_crew.cli is the already-guarded _bootstrap._import_cli — a third guard would protect zero invocations while adding an import-time exit to the most-imported module.
  • Change: guard in src/kiro_crew/_bootstrap.py (skips the cli import on the console-script path), guard in src/kiro_crew/__main__.py (python -m path, which also covers the desktop launchers), spec paragraph in docs/system-specs/modules/cli.md declaring --version the one pre-dispatch fast-path (including the skipped editable-install self-heal), and new test/test_cli_version_fastpath.py (3 tests, see Tests). cli.py itself is untouched; argparse output for every other argv shape is unchanged.

Gate coverage: what the fast-path costs, and where it is paid back

Nine sites shell out to --version as an install smoke. Because bare --version now answers before kiro_crew.cli is imported, those sites no longer prove the import chain resolves — so an undeclared runtime dependency (imported in code, absent from setup.cfg, therefore invisible to pip) could pass a smoke it used to fail. Each site is accounted for:

Site State after this PR
packaging/build-desktop.sh:509 (Linux) companion import kiro_crew.cli probe added
packaging/build-desktop.sh:665 (Windows) companion import kiro_crew.cli probe added
docker/Dockerfile:137 (wheel install in image build) companion import kiro_crew.cli probe added
.github/workflows/docker-smoke.yml:157 covered indirectly — its image is built from the Dockerfile above
test/e2e/scenarios/test_wheel_install.py:132 covered by its adjacent doctor run
.github/workflows/build.yml:68 (build-wheel smoke) gap — needs a maintainer
.github/workflows/build.yml:193 (Windows backend smoke) gap — needs a maintainer
.github/workflows/nightly.yml:187 gap — needs a maintainer
.github/workflows/ota-test.yml:89 not a gate (|| true)

docs/build/desktop-app.md and docs/ci/ci-and-reviews.md are updated so no doc still describes bare --version as import-chain proof.

The four remaining gaps are not deferred by choice. The one-liner that closes each is python -c "import kiro_crew.cli" appended after the --version smoke — the same probe already added to the three sites above. Every one lives under .github/workflows/, which a fork PR cannot edit: fork-workflow-guard.yml blocks the change until a maintainer applies allow-fork-workflow-change, and it strips that label again on the next push. So this needs a maintainer decision, either:

  1. apply allow-fork-workflow-change and I add the three probes to this PR, or
  2. land the workflow probes separately in the same merge window, or
  3. accept the gap on the record, if undeclared-dependency coverage is considered to live elsewhere (for example a kirocrew doctor run in the wheel-install test).

Option 1 or 2 is preferable: the gap is open the moment this ships.

Tests

  • New test/test_cli_version_fastpath.py (subprocess-based, like test_cli_lazy_imports.py): exact-output parity (kirocrew <version>, exit 0) on the -m and _bootstrap entries, plus test_cli_import_never_exits pinning that importing cli under a --version-shaped argv simply imports. All subprocess.run calls pin encoding="utf-8" per the subprocess-encoding gate.
  • Existing suites run locally against the same code: test_cli_lazy_imports.py + test_cli_version_fastpath.py 46 passed. Full suite left to CI.
  • Lint/gates run locally: isort, flake8, mypy (1470 files), black gate, docs-lint, check_comment_history.py, check_brand_name.py, check_feature_map.py, check_changelog_history.py, check_harness_parity.py, check_focus_cue.py, check_testpaths_coverage.py, check_subprocess_encoding.py, and bash -n packaging/build-desktop.sh — all pass.

Manual verification

  • python -m kiro_crew --version prints kirocrew <version>: ~255ms before -> ~68ms after (3 runs); console-script path (_bootstrap.main, argv=[kirocrew, --version]): ~67ms.
  • artifact show --help still offers --version VERSION (int flag); top-level --help and the bare-run banner are unchanged.
  • bash -n passes on the edited packaging/build-desktop.sh; new probe lines mirror the adjacent gate lines flag-for-flag (PYTHONNOUSERSITE=1, -s on Windows).
  • __version__ resolves through the same BUILD_VERSION-aware resolver in kiro_crew/__init__, so the fast-path keeps distribution-stamp parity.

Related Issues

no linked issue: enhancement with no tracking issue.

Checklist

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

Contribution License Agreement

@Arin016
Arin016 requested review from a team and iamwhatever September 5, 2026 15:52
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 5, 2026
@dwu96

dwu96 commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR's description is missing some required sections from our PR template. Workflow runs won't be auto-approved until the description is updated.

Missing sections:

  • ## Problem / Motivation
  • ## Why it matters
  • ## What changed
  • ## Tests

Please update your PR description to include these sections, then push or re-save the description. The workflows will be approved on the next cycle.

1 similar comment
@iamwhatever

Copy link
Copy Markdown
Contributor

👋 Hi! This PR's description is missing some required sections from our PR template. Workflow runs won't be auto-approved until the description is updated.

Missing sections:

  • ## Problem / Motivation
  • ## Why it matters
  • ## What changed
  • ## Tests

Please update your PR description to include these sections, then push or re-save the description. The workflows will be approved on the next cycle.

@github-actions

github-actions Bot commented Sep 5, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of c211945d2120234ddd3b530d99e480e2bdd3c580 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Verified against the base: argparse's version string at cli.py:1248 is kirocrew {__version__} (exact parity with the guards), kiro_crew/__init__ is stdlib-only so the _bootstrap module-scope __version__ import respects that file's stdlib invariant, and the --version reuse in artifact show is real. The design tension the PR itself documents — smoke-gate erosion at workflow sites a fork can't edit — is the one item that survives.

Design-Verdict: CONCERNS

Merging this alone opens the acknowledged gap: three CI smoke gates stop proving the import chain until a maintainer lands the workflow probes.

Watch

The fast-path answers before kiro_crew.cli is imported, so build.yml:68, build.yml:193, and nightly.yml:187 ("gap — needs a maintainer") pass on a wheel whose undeclared runtime dependency only fails at the user's first real command. The PR is honest that "the gap is open the moment this ships" — so treat options 1/2 as a merge precondition, not a follow-up.
Clears when: allow-fork-workflow-change is applied and the three import kiro_crew.cli probes land in this PR, or a maintainer's companion workflow PR merges in the same window.

Suggestions

  • The kirocrew {__version__} line now exists in three unpinned copies (two guards + cli.py:1248); add a parity assertion in test_cli_version_fastpath.py using a non-bare argv shape (e.g. --verbose --version) that reaches argparse, so format drift between entry paths can't ship silently.

[DESIGN-REVIEWED] c211945

@github-actions

github-actions Bot commented Sep 5, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed c211945d2120234ddd3b530d99e480e2bdd3c580 via the fork AI-review pipeline; updated in place on each push.

Review details

FINDING -- src/kiro_crew/_bootstrap.py:46 -- "imports nothing but asyncio" contradicts the actual logging/os/re imports -> Fix: say it uses only stdlib dependencies.
[GPT-REVIEWED] c211945

@github-actions

github-actions Bot commented Sep 5, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of c211945d2120234ddd3b530d99e480e2bdd3c580 via the fork AI-review pipeline — 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.

All contract claims verified against the base tree: output parity holds (cli.py:1248 prints exactly kirocrew {__version__}), the nine --version smoke sites match my grep exactly, the only entry-path importer of kiro_crew.cli is _bootstrap._import_cli (other importers are function-local circular imports inside already-running CLI code), the wheel-install e2e does run doctor adjacently, and fork-workflow-guard.yml with the allow-fork-workflow-change label is real. The base spec pin ("all invocation forms land in cli.main()") is rewritten openly with the skipped steps declared, not recast as a gap.

First-Principles-Verdict: CONCERNS

Merging this opens an undeclared-dependency blind spot in three CI gates the fork cannot patch; a maintainer must act in the same window.

Not justified as shipped

  • Item 6 — rides along, unfinished by constraint: three --version smokes (build.yml:68, build.yml:193, nightly.yml:187) stop proving the import chain the moment this lands, and only a maintainer can add the probes.

What this change ships

Inventory (8 items) — 7 justified

Intent: make bare kirocrew --version answer at interpreter-startup cost instead of paying cli.py's ~250ms module scope — an ADDITION (perf fast-path).

  1. Bare --version answers ~4x faster on the console-script path — justified
  2. Same fast-path on python -m / desktop-launcher path — justified
  3. --version no longer runs platform boot or the editable-install self-heal — justified
  4. Docker image build now also probes import kiro_crew.cli — justified
  5. Desktop build self-containment gate (Linux+Windows) gains the same probe — justified
  6. Three CI --version smokes weakened with no probe added — rides along; gap open at merge, fixable only by a maintainer
  7. Spec paragraph + two doc corrections declaring the fast-path — justified
  8. New 3-test file pinning fast-path output and that importing cli never exits — justified

Watch

  • The description's own words: "the gap is open the moment this ships." Nine smoke sites counted (grep --version across packaging/, docker/, .github/, test/e2e — matches the PR's table); three remain gates that now prove only "console script exits 0". Clears when: python -c "import kiro_crew.cli" lands at build.yml:68, build.yml:193, nightly.yml:187 (option 1 or 2), or a maintainer records option 3 on the PR.

[FIRST-PRINCIPLES-REVIEWED] c211945

@github-actions

github-actions Bot commented Sep 5, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed c211945d2120234ddd3b530d99e480e2bdd3c580 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] c211945

@Arin016
Arin016 force-pushed the feat/version-fast-path branch from c3d5ddc to 821b646 Compare September 5, 2026 17:38
@Arin016

Arin016 commented Sep 5, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the reviews — v2 (821b646, single commit) addresses each point:

  • Design (shadowed guard / __main__.py hazard): dropped __main__.py from the cli.py prog tuple, so no foreign python -m <tool> --version host can ever trip it. Kept the cli.py guard itself rather than deleting it: the frozen desktop binary invokes cli.main() directly without passing through either entry guard (per cli.md Entry Point), so this guard is the only one covering that path.
  • First Principles (3 copies / spec contradiction / dead except): _bootstrap try/except ImportError removed (unreachable — module scope already imports from kiro_crew); spec paragraph rewritten so bare --version is declared as the one pre-dispatch fast-path (skips the cli.main() prelude entirely) instead of contradicting the dispatch invariant. Kept all three guards — each entry stays at interpreter cost and the frozen path has no other cover — happy to collapse further if maintainers prefer.
  • GPT (hoist imports): import sys and __version__ hoisted to module scope in __main__.py; __version__ hoisted in _bootstrap.py with the docstring allowance extended (same asyncio-only rationale as dep_sync).
  • Design (parity test): added test/test_cli_version_fastpath.py — 6 subprocess tests pinning exact kirocrew <version> output on all three entries, non-bare fallthrough, and foreign-prog non-exit including the __main__.py regression pin. Green locally (6 passed) with a mutation check, plus test_cli_lazy_imports.py (40) and test_bootstrap.py (11) green; full suite to CI.

@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 Sep 5, 2026
@Arin016
Arin016 force-pushed the feat/version-fast-path branch from 821b646 to 425410f Compare September 5, 2026 18:00
@Arin016

Arin016 commented Sep 5, 2026

Copy link
Copy Markdown
Contributor Author

v3 (425410f, single commit) concedes the BLOCK — verified the launcher evidence (build-desktop.sh exec python3.12 -s -m kiro_crew, find-bin.js backend layout) and the importer grep: the cli.py guard had zero real consumers, so it is deleted rather than defended. cli.py is now untouched; the two entry guards plus the trimmed test (test_cli_import_guard_prints_version and the foreign-prog pins removed, test_cli_import_never_exits kept to pin the absence of import-time exits) and a two-guard spec paragraph remain.

Also fixed the Backend Lint & Type Check failure: it was black 26.3.1 wanting the parametrized def collapsed — gone with that test. black --check, flake8, and isort --check are now clean on every touched file, and locally test_cli_version_fastpath (3), test_cli_lazy_imports (40), and test_bootstrap (11) all pass.

@Arin016
Arin016 force-pushed the feat/version-fast-path branch from 425410f to 03041f2 Compare September 6, 2026 10:16
@Arin016

Arin016 commented Sep 6, 2026

Copy link
Copy Markdown
Contributor Author

v4 (03041f2, single commit) answers the BLOCK per gate:

  • packaging/build-desktop.sh (both self-containment gates — fixed in-PR): each PYTHONNOUSERSITE=1 ... -m kiro_crew --version gate (mac + Windows, same error message) gained a companion ... -c 'import kiro_crew.cli' probe, with the gate comment updated to say why --version alone no longer proves the chain. bash -n clean; docs/build/desktop-app.md updated to match.
  • build.yml, docker-smoke.yml, Dockerfile (pip-install-then-smoke — intentionally untouched): pip resolves declared dependencies at install time, so a missing-dep artifact cannot arise there the way it can in the pruned desktop bundle; wheel-content coverage already lives in the vendored-payload gate. Touching the two workflow files from a fork also needs the allow-fork-workflow-change label per the fork guard. Offered in the description: append python -c "import kiro_crew.cli" after each --version smoke if maintainers want it — say the word and I will add it (plus Dockerfile, which has no such constraint).
  • FP leftovers: cli.md universality sentence fixed ("every command invocation ... lands in cli.main()") and the self-heal skip is now declared in the spec paragraph and description.
  • Lint failure: was the subprocess-encoding gate (my test used bare text=True); both call sites now pin encoding="utf-8", and I ran the real upstream check_subprocess_encoding.py plus black/flake8/isort green on every touched file.
  • Windows (2) failure: test_write_goes_through_atomic_helper (dashboard PUT lock race) — 1 of 20,611, in code with zero overlap with this diff. Looks flaky/unrelated; requesting a maintainer re-run to confirm.

@Arin016 Arin016 closed this Sep 7, 2026
@Arin016
Arin016 deleted the feat/version-fast-path branch September 7, 2026 04:48
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Sep 7, 2026
@Arin016
Arin016 restored the feat/version-fast-path branch September 7, 2026 04:49
@Arin016 Arin016 reopened this Sep 7, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 7, 2026
@iamwhatever
iamwhatever force-pushed the feat/version-fast-path branch from c5c9c30 to 9448950 Compare September 13, 2026 13:45
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision readiness: action required A blocking check or review needs attention labels Sep 13, 2026
@Arin016

Arin016 commented Sep 13, 2026

Copy link
Copy Markdown
Contributor Author

Happy with the co-authored rebase and the extensions (Dockerfile probe, workflow-lane documentation) — no pr-no-autofix from me. Thanks for picking this up; standing by for CI and review.

@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 Sep 13, 2026
Bare `kirocrew --version` needs none of the ~250ms module-scope
imports it currently pays for (apps.builtins, cli_doctor, history
chain). Answer it in _bootstrap (console script) and __main__
(python -m, covering the desktop launchers) with output identical
to argparse, and restore the self-containment gates that read the
flag as import-chain proof with an explicit `import kiro_crew.cli`
probe: both `packaging/build-desktop.sh` gates and the wheel-install
gate in `docker/Dockerfile`. Only the bare form fast-paths, so
`artifact show --version N` keeps its meaning.

The pip-install lanes under `.github/workflows/` still read bare
`--version` as chain proof; `docs/ci/ci-and-reviews.md` records what
that smoke does and does not cover, since a fork PR cannot edit them.

Co-authored-by: iamwhatever <12429733+iamwhatever@users.noreply.github.com>
@iamwhatever

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: iamwhatever#241cc860]:

The finding holds. After this PR kirocrew <version> is produced from three unpinned places: the _bootstrap guard, the __main__ guard, and argparse's version= action at cli.py:1248. test_cli_version_fastpath.py pins the two guards to each other and to the version resolver, so drift between a guard and the argparse copy is the one direction nothing catches.
Deferred rather than fixed here because the assertion needs a non-bare argv shape chosen by reading cli.py's parser, and a test whose chosen shape does not actually reach the argparse version action is a test that passes for the wrong reason. That is a small piece of independent work, not a line to append inside a perf change.
Tracked as #10558 with the deferred-finding label, an assignee and a Due: date, so this is not an untracked deferral.
This ruling covers the parity-of-duplicated-version-output class generally: findings that ask for a cross-entry-path format assertion on this PR's version line are covered by it, wherever a later round places them.

self-added: yes — the two guards this PR adds are two of the three copies.
mechanism: argv-guard fast-path printing f"kirocrew {__version__}" on both entry paths.

@iamwhatever

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: iamwhatever#241cc860]:

  • Three .github/workflows smokes lose import-chain proof — needs-a-decision (span=8f8ff701bbb7).

The finding holds and is not disputed: build.yml:68, build.yml:193 and nightly.yml:187 shell out to bare --version, which after this PR answers before kiro_crew.cli is imported. A runtime dependency that is imported in code but absent from setup.cfg is invisible to pip, so those three lanes go green on a wheel that crashes at the user's first real command.
This is not deferred by choice. The fix is one line per site — python -c "import kiro_crew.cli" after the --version call, exactly the probe already added at packaging/build-desktop.sh:509, :665 and docker/Dockerfile:137. All three sites live under .github/workflows/, which fork-workflow-guard.yml blocks for fork PRs until a maintainer applies allow-fork-workflow-change, and it strips that label again on the next push. Adding the probes from this fork would turn PR Readiness red and keep it red, so the constraint is structural rather than a scope choice.
The question for a maintainer, one of three: (1) apply allow-fork-workflow-change and I add the three probes to this PR; (2) land them in a maintainer-side workflow PR in the same merge window; (3) record on this PR that the gap is accepted because undeclared-dependency coverage lives elsewhere, for example a kirocrew doctor run in the wheel-install test. Option 1 or 2 is preferable, since the gap opens the moment this ships.
No issue is filed: three candidate options are a ruling to make, not a task anyone but the maintainer can pick up.
This ruling covers every instance of the fork-cannot-edit-.github constraint on this PR, wherever a later finding places it.

self-added: no — the sites pre-exist; this PR changes what the flag they call proves.
mechanism: bare --version argv guard returning before the kiro_crew.cli import.

@iamwhatever

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: iamwhatever#241cc860]:

  • Item 6 rides along, unfinished by constraint — needs-a-decision (span=765ba6748bd6).

Agreed on the facts, including the characterisation: three --version smokes stop proving the import chain the moment this lands, and only a maintainer can add the probes. fork-workflow-guard.yml gates .github/** for fork PRs and re-strips allow-fork-workflow-change on every subsequent push, so this is a structural constraint on who is permitted to make the edit, not a scope choice by the author.
What has changed since the round that raised this: everything fixable from a fork is now fixed rather than described. docker/Dockerfile:137 carries the companion probe, docs/build/desktop-app.md carries the caveat at both its line-111 and line-332 sites, docs/ci/ci-and-reviews.md records what the wheel-lane smoke does and does not cover, and the PR body carries a nine-row table naming every --version install-smoke site with its state. The unfinished remainder is exactly three workflow lines and nothing else.
The maintainer question is the one put under the design lane's own workflow-gap item: apply allow-fork-workflow-change so this PR carries the probes, land them alongside in the same merge window, or record acceptance of the gap.
No issue is filed, because this is a decision to make rather than a task to pick up.

self-added: no — this PR changes the meaning of pre-existing gate lines.
mechanism: bare --version argv guard returning before the kiro_crew.cli import.

@iamwhatever

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: iamwhatever#241cc860]:

  • Nine counted smoke sites, three still proving only "console script exits 0" — needs-a-decision (span=12f5202d313d).

The count is confirmed and matches independently: nine sites, and the PR body's table now names each one with its state. Six are accounted for. packaging/build-desktop.sh:509 and :665 and docker/Dockerfile:137 carry companion import kiro_crew.cli probes. docker-smoke.yml:157 is covered indirectly, because the image it smokes is built from that Dockerfile, so a broken chain fails the build before the smoke runs. test/e2e/scenarios/test_wheel_install.py:132 is covered by its adjacent doctor run. ota-test.yml:89 is not a gate at all, since it ends in || true.
The three that remain gates — build.yml:68, build.yml:193, nightly.yml:187 — are precisely this item's Clears when list, and all three are under .github/workflows/, which a fork PR cannot edit while fork-workflow-guard.yml stands.
So this item clears by a maintainer taking option 1, 2 or 3 from the PR body, and cannot clear from inside this PR. No issue is filed: an issue whose body lists candidate designs and asks which to take is unactionable by anyone but the maintainer.

self-added: no — the sites and their wording pre-exist this PR.
mechanism: bare --version argv guard returning before the kiro_crew.cli import.

@iamwhatever

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: iamwhatever#241cc860]:

Verified and the finding holds: src/kiro_crew/__init__.py imports asyncio, logging, os and re, so the enumeration in that comment is out of date.
What the clause is load-bearing for is unaffected, and this is not a defect in shipped behaviour. The comment justifies a module-scope package import inside the one file whose job is to heal a broken editable install, and the property that justification needs is that the imported module cannot itself raise ModuleNotFoundError. All four of those imports are standard library, so the property holds and the import stays safe. The wrong part is the list, not the reasoning it supports.
Deferred rather than patched because the clause predates this PR and is inherited: this diff reworded the surrounding comment to cover the added __version__ import and carried the existing wording along with it. Rewording it properly means finding every copy of the claim and fixing them in one pass, which is a comment-accuracy change with a different blast radius from a --version fast-path.
Tracked as #10557 with the deferred-finding label, an assignee and a Due: date.
This ruling covers the stale-stdlib-enumeration class in this comment block wherever a later round places it.

self-added: yes — the diff restates the clause on an added line.
mechanism: module-scope from kiro_crew import __version__, dep_sync with its justifying comment.

@Arin016

Arin016 commented Sep 13, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for carrying this over the line — the rebase, the Dockerfile probe, and the recorded workflow gap all look right, and both remaining CONCERNS converge on the same maintainer-only item (the three workflow smokes), which I agree should land via your side since a fork cannot edit or validate .github/workflows/* here.

One offer on the Design suggestion (argparse-parity pin): happy to push this to the branch, or leave it with you — verified the mechanism locally (--verbose --version reaches argparse, prints the identical line, exit 0, empty stderr):

def test_verbose_version_reaches_argparse(self, tmp_path: Path) -> None:
    """A non-bare flag combo must reach argparse and print the same line."""
    res = _run_probe(
        "import sys; sys.argv = ["kirocrew", "--verbose", "--version"];"
        " from kiro_crew.cli import main; main()",
        tmp_path,
    )
    assert res.returncode == 0
    assert res.stdout == _EXPECTED_VERSION_LINE

Note the snippet above needs its inner quotes fixed (I had to flatten quoting for this comment) — the real form is sys.argv = ['kirocrew', ...] style single-quoted argv like the neighboring tests. Standing by either way.

@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 Sep 13, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: iamwhatever#241cc860]: Ready for maintainer review — readiness: passed on head c211945d2120234ddd3b530d99e480e2bdd3c580. 85 checks, 0 failing, 0 pending. All four AI lanes stamped this head: GPT 5.6 and Opus 4.8 report no blocking findings; Design, First Principles and UX are CONCERNS (advisory), and all five raised items carry a disposition record from a verified writer with no rule violations.

@Arin016 — thanks for the patience on this one. Your v6 was already green but the checks had gone stale and the branch was ~230 commits behind, so I rebased it onto current main and kept you as the commit author with myself as co-author. I also carried two of your review items further than v6 did; nothing about your approach changed. Please sanity-check the pieces I added, and say the word if you'd rather I back any of them out.

What changed since v6

Your --version fast-path and your two packaging/build-desktop.sh probes are untouched. Three lanes independently made the same point about the other sites that read bare --version as import-chain proof, so I completed that work where a fork PR is permitted to:

  • docker/Dockerfile:137 — added the companion python -c 'import kiro_crew.cli' probe. This also restores docker-smoke.yml:157 indirectly, since the image it smokes is built from this Dockerfile.
  • docs/build/desktop-app.md — the caveat now sits at the line-332 site as well as the line-111 one you already amended. First Principles caught that sibling.
  • docs/ci/ci-and-reviews.md — records what the wheel-lane smoke does and does not cover.
  • PR body — rewritten with a table accounting for all nine --version install-smoke sites and their state. The old body claimed the Dockerfile was "intentionally untouched", which the diff then contradicted; GPT blocked on exactly that mismatch and cleared once the body matched the code.

Worth noting for anyone reading the earlier rounds: GPT's suggested fix for that finding was to delete the Dockerfile hunk. I kept the hunk and fixed the prose instead, because removing it would have re-opened the Design lane's own round-1 request for that probe and deleted real coverage.

One decision needed from a maintainer

Three sites still read bare --version as chain proof and are the only unfinished part of this change:

  • .github/workflows/build.yml:68
  • .github/workflows/build.yml:193
  • .github/workflows/nightly.yml:187

The fix is one line each — python -c "import kiro_crew.cli" after the --version call, the same probe used everywhere else. All three are under .github/workflows/, which fork-workflow-guard.yml blocks for fork PRs until a maintainer applies allow-fork-workflow-change, and it strips that label again on the next push. Adding them from this fork would turn readiness red and hold it there, which is why they are dispositioned as needs-a-decision rather than deferred to an issue.

Pick whichever you prefer:

  1. Apply allow-fork-workflow-change and I add the three probes to this PR.
  2. Land them in a maintainer-side workflow PR in the same merge window.
  3. Record here that the gap is accepted, if undeclared-dependency coverage is considered to live elsewhere — for example a kirocrew doctor run in the wheel-install test.

Option 1 or 2 is preferable: an undeclared runtime dependency (imported in code, absent from setup.cfg, so invisible to pip) would pass those three lanes and first surface at a user's first real command. The window opens the moment this merges.

Deferred, tracked

Both carry the deferred-finding label, an assignee and a due date.

Verification

Local gates run green against base 47d78f6233f0: isort, flake8, mypy (1470 files), the black gate, docs-lint, check_comment_history.py, check_brand_name.py, check_feature_map.py, check_changelog_history.py, check_harness_parity.py, check_focus_cue.py, check_testpaths_coverage.py, check_subprocess_encoding.py, check_agent_sdk_boundary.py, check_sync_io_in_async.py, check_lockdown_before_publish.py, check_loop_bound_locks.py, and bash -n packaging/build-desktop.sh. test_cli_version_fastpath.py plus test_cli_lazy_imports.py give 46 passed, and python -m kiro_crew --version answers kirocrew 0.7.0 with exit 0.

Still one commit on main, still not draft. The only thing left is human review.

@Arin016

Arin016 commented Sep 13, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the thorough disposition — the verification list and the two tracked issues (#10557, #10558) look right, and I am fine with both deferrals.

On the needs-a-decision item: option 1 works for me. Apply allow-fork-workflow-change and I will add the three import kiro_crew.cli probes to this PR immediately (same one-liner pattern as the desktop/Dockerfile gates, which I have already validated). Say the word if you would rather do option 2 or record option 3 instead.

@iamwhatever

Copy link
Copy Markdown
Contributor

Not approving for now: the recorded dispositions still carry three needs-a-decision items for the build.yml:68, build.yml:193 and nightly.yml:187 smokes that stop proving the import chain once the fast path lands, and the thread is waiting on a maintainer to apply allow-fork-workflow-change so the probes can be added. That decision should land before approval.

@bolichen97
bolichen97 merged commit 290262d into kirodotdev:main Sep 13, 2026
94 of 100 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 13, 2026
@NicholasRBowers NicholasRBowers removed the drive-to-green PR claimed by drive-to-green pipeline label Sep 13, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants