Skip to content

docs(app-kit): state that hooks apps self-provision Python deps - #9774

Merged
bolichen97 merged 1 commit into
mainfrom
fix/document-hooks-app-python-deps-7879
Sep 10, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/document-hooks-app-python-deps-7879

Conversation

@dwu96

@dwu96 dwu96 commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Fixes #7879

Symptom

An app that declares only backend.hooks gets no requirements.txt provisioning, and docs/app-kit/manifest-reference.md's backend.hooks section said nothing about Python dependencies — an author had no way to learn the limitation, the one mechanism that does serve hooks, or the .venv naming trap.

Root cause

Documentation gap. Hooks are imported into the Gateway process; runtime provisioning is deliberately reachable only from spawned surfaces, and front-placing an app-controlled tree on the Gateway's import path is forbidden by the trust rule in _provision_app_deps_locked's docstring (src/kiro_crew/apps/backend.py:1264-1277) and the -m kiro_crew... carve-out (docs/app-kit/manifest-reference.md:57-59). Per the issue's own framing, a documented statement resolves it; the mechanism half is a platform design ruling and is out of scope here.

Fix (documentation only — no behaviour change)

  • docs/app-kit/manifest-reference.md: a "Python dependencies" note at the end of the backend.hooks section stating (1) runtime provisioning runs only on the backend-spawn and stdio-MCP paths, and hook code gets nothing from it; (2) the provisioned tree reaches spawned children via the deps_boot shim / PYTHONPATH and is never on the Gateway's import path, with the shadowing rule made binding on hook authors; (3) the install-time build step is what serves hooks, with its real gates (registry installs only, package.json precedence, pip failure fails the install, desktop bundled interpreter fails outright); (4) the .venv naming hazard, scoped to the shapes that can actually trigger it.
  • docs/app-kit/publishing-guide.md:492-494: the pre-existing "missing toolchain is a logged skip" sentence narrowed to npm — the pip step hard-fails — because the new note cross-references this flow and the sentence was wrong for pip (code docstring staleness tracked in Registry install: missing pip hard-fails the build despite docs and docstring claiming a soft skip #9770).

Corrections to the issue as filed

Verification (every doc claim anchored to source at the verified SHA)

  • Two provision_app_deps callers: backend spawn src/kiro_crew/apps/backend.py:1842 (gated on a real file entry point, backend.py:1831-1842) and stdio MCP registration src/kiro_crew/apps/bridges.py:2694. Neither is the hooks path.
  • start_app_backend early-returns when entryPoint is unset: backend.py:764-765.
  • src/kiro_crew/apps/hooks_integration.py: zero occurrences of requirements, deps_dir, app_deps, or sys.path.
  • Transport is Shim-XOR-PYTHONPATH (backend.py:2117-2177): deps_boot (site.addsitedir) for Python commands, PYTHONPATH only on a positive ABI match; deps_boot.py is a launch shim for spawned app processes only — the Gateway never adds an app deps tree to its own sys.path.
  • Install-time build: registry.py::_run_app_build (registry.py:6047-6184) runs pip install . / -r requirements.txt on sys.executable in the subdirectory-joined app_source (registry.py:5970); package.json takes precedence (if/elif, registry.py:6070/6085); npm-only soft skip (registry.py:6081-6084); nonzero pip fails the install (registry.py:6177-6184); desktop bundled interpreter fails outright (registry.py:6123-6132).
  • Gates: full backend suite failing-id sets byte-identical BOTH directions vs an origin/main worktree (108 = 108 pre-existing environmental ids, identical invocation pytest -q -n auto --dist loadgroup). Frontend cross-surface guards: 230 files / 6,418 tests passed. check_comment_history.py, docs_lint.py, check_black_formatting.py all pass; no narration phrases or non-inclusive terms in the diff.
  • Review: two model-pinned lanes (gpt-5.6-sol, claude-opus-5), five rounds each, converged PASS/PASS on the final prose. Adopted along the way: shim-vs-PYTHONPATH transport, the install-time-build path serving hooks, pip hard-fail vs the stale soft-skip claim, package.json precedence, subdirectory precision, .venv hazard scoped to spawned surfaces. Declined with evidence: bare #NNNN refs (precedent at docs/app-kit/api-reference.md:210).

No frontend change; the diff is documentation prose, so there is no visual delta a screenshot could evidence.

Pattern harvest

Rule candidate: when documenting a capability gap, anchor every sentence to a source line and enumerate the reachable states exhaustively — the review rounds here showed each unanchored generalization ("via PYTHONPATH", "a missing pip is a logged skip", "always the case for a hooks-only app") concealed a real behavioural fork (if/elif precedence, npm-vs-pip asymmetry, call-site gating) that would have misled the exact audience the note targets. Knowingly out-of-scope sibling: the stale soft-skip wording in registry.py:6062-6066's docstring (#9770).

An app declaring only backend.hooks runs inside the Gateway process, so
requirements.txt provisioning (backend-spawn path + stdio MCP
registration) does not apply to it, and the provisioned tree is only
reached by spawned children. The backend.hooks section said nothing
about this. Add a Python-dependencies note stating the limitation as
fact, with the .venv naming hazard (resolve_app_python prefers a
probe-usable app venv for spawned work even when it holds nothing).

Fixes #7879
@dwu96
dwu96 requested review from a team and Zedmor September 9, 2026 21:28
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 9, 2026
@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 2ed6abb0e10aee05aaffa5053a3d90baac577d0b and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2ed6abb

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

@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

All claims verified against source. The diff is docs-only; every behavioral statement in the new prose matches the code (the two provision_app_deps call sites at backend.py:1842 and bridges.py:2694, the if/elif package.json precedence and pip hard-fail in registry.py::_run_app_build, the probe-gated .venv preference in interpreter.py::resolve_app_python, zero deps references in hooks_integration.py), and the publishing-guide sentence it narrows was genuinely wrong for the pip branch. The docs-only shape is dictated by a real trust boundary — an app-controlled tree on the Gateway's import path could shadow Gateway code — so documenting the install-time build as the mechanism that serves hooks is the correct design, not a symptom patch.

Design-Verdict: PASS

Accurate, source-anchored documentation of a real capability boundary; docs-only is the right shape because the mechanism alternative is forbidden by the Gateway trust rule.

[DESIGN-REVIEWED] 2ed6abb

@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 2ed6abb0e10aee05aaffa5053a3d90baac577d0b — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 2ed6abb

Verdict parsed from the review's SHA-scoped output markers for commit 2ed6abb0e10aee05aaffa5053a3d90baac577d0b.

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

@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 Sep 9, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) September 10, 2026 04:41

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

Maintainer review (agent-assisted, on behalf of @bolichen97), head 2ed6abb0e.

Docs-only; both files accounted for. Every load-bearing claim in the new backend.hooks note holds against main: provision_app_deps has exactly two callers (apps/backend.py:1853, gated on a real file entry point, and bridges.py:2694), and start_app_backend returns early for hooks apps, so hooks apps do self-provision. Consistent with app-kit-platform.md.

Nit: manifest-reference.md:647 carries (see #7878 / #7901 for the mechanism) — a history reference in reader-facing docs; droppable.

@bolichen97
bolichen97 merged commit 092f47f into main Sep 10, 2026
64 checks passed
@bolichen97
bolichen97 deleted the fix/document-hooks-app-python-deps-7879 branch September 10, 2026 05:01
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 10, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…dotdev#9774)

An app declaring only backend.hooks runs inside the Gateway process, so
requirements.txt provisioning (backend-spawn path + stdio MCP
registration) does not apply to it, and the provisioned tree is only
reached by spawned children. The backend.hooks section said nothing
about this. Add a Python-dependencies note stating the limitation as
fact, with the .venv naming hazard (resolve_app_python prefers a
probe-usable app venv for spawned work even when it holds nothing).

Fixes kirodotdev#7879

Co-authored-by: Di Wu <dwu96@users.noreply.github.com>
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.

No supported way to declare Python dependencies for a backend.hooks app

2 participants