Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Monorepo tooling layout

Delivery Summary

  • Beads feature root: dstack-mol-7s4
  • Status: delivered
  • Pull request: not created; delivered by local fast-forward merge
  • Merge commit: 3da287c59c1ff7d22792f3a3f1f37c048477d8a7
  • Design record: design.md

Delivered Capability

dstack can create and update bounded monorepos with 1-32 explicit packages. One root mise configuration owns the profile-tool union, aggregate checks, lockfile, and provisioner. Task-only package configurations execute profile checks from package roots, while root hk applies package-prefixed changed-file formatting policy.

User-Facing Behavior

Setup and update accept an explicit repository layout and complete package objects containing preserved display names, filesystem-safe slugs, normalized paths, and canonical language profiles. Validation rejects malformed, reserved, overlapping, case-colliding, or symlinked paths before rendering. Older answers remain single-package until explicit conversion. Root mise run check executes every package; pre-commit and fix select package source by path.

Design Integration

Copier remains recorded scaffold authority. The root remains workflow, documentation, tool-version, lock, and hook authority. Deterministic package configs contain commands but no tools. Previously recorded package configs are managed and refresh with current answers; newly occupied non-managed destinations preserve their bytes and receive a canonical adoption candidate that blocks update completion until reconciled. No package discovery, nested workspace support, progress manifest, or second lock authority was introduced.

Operational Impact

Layout preflight reports exact destinations and collisions. Unresolved Copier conflicts or package candidates skip provisioning, documentation, and Beads checks and return a nonzero status. Candidate retries preserve both project and generated bytes. The existing tooling recovery command remains python3 scripts/setup-tooling.py --json.

Reference and Contracts

Generated monorepos also contain a Copier-owned docs/src/reference/repository-layout.md page and conditional summary entry.

Validation Evidence

  • Stable mise 2026.7.5 compatibility with experimental behavior disabled: passed.
  • Named monorepo integration partition: passed.
  • Homogeneous, mixed, and 32-package matrices: passed; maximum render completed in 94.55 seconds.
  • Exact full-check execution, changed-path selection, byte-stable rendering, conflict, and candidate retries: passed.
  • HK_JOBS=1 mise run check: passed.
  • uv run --frozen --group test pytest: 257 passed, 1 skipped.
  • Beads dependency-cycle validation: passed with no cycles.
  • Isolated implementation and final integration reviews: passed with no blockers.

Design Reconciliation

Delivered as Designed

Explicit bounded package answers, strict preflight, stable namespaced mise tasks, one root lock/provisioner, package-root checks, changed-path hk policy, additive update preservation, generated layout documentation, and maximum-size evidence are delivered.

Intentional Changes

The compatibility spike selected mise’s stable native monorepo task paths with explicit config roots and root lockfile opt-in. Because Copier cannot emit an answer-dependent number of destination files, the trusted setup/update helpers render deterministic package configs directly from Copier-recorded answers without introducing separate state. Any newly occupied non-managed destination produces an exact-byte candidate rather than silent replacement.

Deferred Work

Nested workspaces, automatic package discovery, package-specific deployment pipelines, and a separate check:changed command remain deferred.

Rejected or Removed Scope

Experimental mise behavior, independent package locks or installers, inferred packages, migration-style checkpoint state, and automatic candidate acceptance remain unsupported.

Documentation Updated

  • docs/src/architecture/index.md
  • docs/src/operations/index.md
  • docs/src/development/index.md
  • docs/src/reference/index.md
  • docs/src/features/monorepo-tooling-layout/design.md
  • skills/setup-project/SKILL.md
  • skills/update-project/SKILL.md
  • generated development, tooling reference, repository-layout, and summary templates

Audit Trail

The reviewed design and graph are recorded in 509ff8e. Implementation commits are 8ce9a73, 433db4c, ff44a78, a59b5bc, and 76aa287. Each bounded task received an isolated review and current validation before commit. The implementation coordinator dstack-mol-5bq closed after all five tasks passed.