Research Bun and TypeScript conventions for human-agent collaboration

[wryenmeek]

Objective

Research Bun and TypeScript repository practices that support humans and coding agents working safely and predictably in the same repository. Use the findings to inform an ADR-level decision for the Knowledgebase project's TypeScript/Bun runtime and test conventions.

This issue is research-first. Do not change production code or enable new runtime behavior as part of the research.

Questions to answer

• When should this repository use TypeScript/Bun instead of the established Python runtime?
• What should be the canonical Bun test runner and conventions for bun:test tests?
• Which package.json scripts, Bun version pinning, lockfile, tsconfig, and build/test commands should be required?
• What conventions improve agent/human collaboration: narrow package boundaries, deterministic tests, explicit fixtures/mocks, safe environment handling, reproducible CI, and clear ownership/documentation?
• How should Bun tests integrate with the repository's existing Python pytest suite without implying that either runner covers the other?
• What security, supply-chain, dependency, and CI considerations are specific to Bun/TypeScript?
• Should the result amend ADR-019/ADR-007, or should it become a new ADR dedicated to TypeScript/Bun conventions?

ADR interaction review

All repository ADRs were screened. The research must explicitly evaluate the following interactions rather than treating ADR-019 as the only relevant decision.

Direct runtime, package, and test governance

• ADR-007 — Control-plane layering and packaging: Confirm whether the Python authoritative-runtime rule and the approved scripts/fleet/** exception are sufficient, or whether TypeScript/Bun needs a clearer package/runtime contract.
• ADR-019 — Fleet Jules orchestration: Revalidate the rationale for TypeScript/Bun, Jules SDK coupling, Bun execution/build conventions, package isolation, and the boundary between Fleet and scripts/kb/**.
• ADR-020 — Post-MVP package-family criteria: Determine what evidence, ownership, tests, write boundaries, and CI workflow requirements a future TypeScript/Bun package family would need.
• ADR-029 — Test framework conventions: Define how the pytest ratchet applies to Python tests while bun:test governs Fleet tests, including naming, discovery, assertions, mocking, coverage, and migration rules.

CI, trust, permissions, and concurrency

• ADR-004 — Split CI workflow governance: Determine which workflow owns Bun install, type-check, build, and test gates, and how those checks preserve CI-1/CI-2/CI-3 trust boundaries.
• ADR-005 — Write concurrency guards: Confirm when TypeScript/Bun code may need repository locks, how it must interoperate with workflow concurrency, and when external GitHub/Jules mutations are intentionally outside the local lock model.
• ADR-015 — Extended CI trust model: Evaluate whether CI-4/CI-5-style workflow permissions and artifact handoffs need Bun-specific treatment.
• ADR-016 — Pre-commit hooks governance: Determine whether Bun formatting, linting, type-checking, or test hooks belong in the existing hook model and how human/agent local environments stay consistent.
• ADR-025 — Runtime-budget contract scope: Decide whether Bun build/test/install and Fleet API stages need explicit runtime budgets, telemetry, or parity with Python workflow stages.
• ADR-027 — Infrastructure validation trigger model: Check whether TypeScript/Bun changes require the same infrastructure-sensitive trigger and validation treatment as other control-plane changes.
• ADR-030 — CLI write confirmation: Verify whether Bun CLI entrypoints with write-capable modes need --apply/approval semantics, and whether the migration contract is language-neutral.
• ADR-031 — Lock-holder PID tracking: Confirm whether any Bun-owned local lock path needs the same holder metadata and diagnostics, or whether Fleet remains external-side-effect-only.

Agent, human, and automation collaboration

• ADR-008 — Agent writes to framework paths: Clarify whether coding agents modifying TypeScript/Bun files need additional path, approval, or review constraints.
• ADR-014 — HITL/AFK work classification: Determine whether Bun/Fleet automation is AFK-eligible, what human gates apply to write-capable operations, and how local agent execution differs from CI execution.
• ADR-017 — Agent persona category taxonomy: Identify whether TypeScript/Bun development belongs to dev-support, kb-workflow, or both, and what routing metadata should be documented.
• ADR-018 — CONTEXT.md vocabulary pattern: Identify the Bun/TypeScript terms, commands, package boundaries, and test conventions that belong in context pages for agents and humans.
• ADR-022 — AFK scripts versus HITL Copilot CLI: Reconcile deterministic Bun automation with the existing rule that AFK writes use scripts while judgment-heavy work uses Copilot CLI.
• ADR-028 — Instruction locality ladder: Decide where Bun conventions should live: package-local README/instructions, shared context, repository instructions, or an ADR, without duplicating guidance.
• ADR-037 — Jules persona memory learning: Check whether Bun/TypeScript lessons can enter Jules memory, what evidence and proposal gates apply, and whether memory updates need Bun-specific validation.

Fleet-specific operational and security decisions

• ADR-032 — Fleet quota-saturation soft-warn: Determine how Bun SDK/API errors, retry behavior, exit codes, and quota saturation should be tested and surfaced to humans and agents.
• ADR-033 — Fleet label-driven dispatch: Verify that Bun implementation and tests preserve label transitions, strike accounting, recovery, and merge-conflict semantics.
• ADR-034 — Fleet no-notification on quota saturation: Check how Bun-side soft-warn behavior maps to notification suppression and operator-visible diagnostics.
• ADR-035 — Tier-3 multi-provider fallback deferral: Identify whether the TypeScript/Bun boundary constrains future provider fallback or whether the runtime choice should remain Jules-specific.
• ADR-036 — Fleet orchestrator GitHub App identity: Evaluate Bun credential handling, least privilege, step-scoped secrets, API mutation safety, sensitive-path gates, and downstream workflow triggering.

Adjacent contracts to verify for non-interference

These ADRs do not currently select the TypeScript/Bun runtime, but the research must verify that Bun/Fleet does not bypass or accidentally redefine their contracts: ADR-001 persistent wiki architecture; ADR-002 frontmatter and SourceRef provenance; ADR-003 policy-gated query persistence; ADR-006 authoritative source boundary; ADR-009 canonical identity and anchors; ADR-010 source conversion compliance; ADR-012 GitHub source monitoring; ADR-013 rejected-source registry; ADR-021 Google Drive monitoring; ADR-023 batch query persistence; ADR-024 synthesis-curator artifact handoff; and ADR-026 checkpoint registry.

For each adjacent ADR, record either the relevant non-interference constraint or why no TypeScript/Bun change is needed.

Research scope

Cover the current scripts/fleet/ runtime, including its package.json, bun.lock, tsconfig.json, TypeScript tests, build commands, workflow usage, and repository documentation. Compare those practices with authoritative Bun and TypeScript documentation and relevant primary-source guidance from maintainers or official tooling documentation.

Inspect all ADRs listed above and distinguish:

1. Current repository facts.
2. Existing ADR requirements.
3. External Bun/TypeScript recommendations.
4. Proposed changes requiring a later approval.

Do not assume that a general JavaScript convention is applicable to Bun without verifying Bun-specific behavior.

Deliverables

1. A repository-grounded research report with links to authoritative sources.
2. An ADR interaction matrix covering every ADR listed above, with findings, conflict risk, and recommended action.
3. A concise gap analysis of current Knowledgebase conventions versus recommended Bun/TypeScript practices.
4. A recommended decision boundary for Python versus TypeScript/Bun, including test-runner ownership.
5. Proposed ADR disposition: amend ADR-019/ADR-007 or create a new ADR, with rationale and an outline of the required decision, consequences, and migration/rollback sections.
6. A concrete checklist for humans and agents contributing to scripts/fleet/.
7. Any follow-up implementation, documentation, or test issues needed to adopt the recommendation.

Acceptance criteria

• Every material external claim is supported by an authoritative citation.
• The report distinguishes current repository facts from external recommendations.
• Every ADR interaction listed above is explicitly addressed, including a no-change rationale for adjacent ADRs where appropriate.
• The recommendation explicitly addresses bun:test, Python pytest, build/type-check validation, CI ownership, dependency reproducibility, security, and agent/human contribution workflows.
• The report identifies whether existing ADRs are sufficient and names the exact ADR section(s) requiring amendment or the proposed new ADR scope.
• No code or workflow behavior is changed until the research recommendation is reviewed and separately approved.

[wryenmeek]

Triage

• Type: documentation
• Severity: medium — the research is needed to resolve repository-wide runtime, test, CI, and agent-collaboration guidance gaps, but no current production behavior is blocked.
• Area: fleet / TypeScript-Bun conventions
• Related: Compliance-rate measurement spike (Phase 1.5) (slice 7) #196, QA gate: read-only classifier real-repo + hallucination audit (qa-f) #207, and First real-use exercise (Phase 7 validation) — cross-surface set-equivalence (slice 10) #212 (audit-workspace validation slices that depend on the telemetry and workflow conventions clarified here).

The existing question, needs-triage, and fleet labels are retained because this remains a research-first governance item awaiting prioritization.