Tooling reference
Files
| File | Contract |
|---|---|
mise.toml | Declares project tools, environment, and named tasks. |
mise.lock | Project-owned resolved downloads; commit it. |
hk.pkl | Defines the shared check/fix/pre-commit step map. |
.config/rumdl.toml | Configures Markdown linting and deterministic fixes. |
.editorconfig | Keeps editor output on UTF-8, LF, final newlines, and no trailing spaces. |
_typos.toml | Ignores hash-like identifiers while retaining typo checks elsewhere. |
contextlint.config.json | Checks documentation links, anchors, and image targets. |
cog.toml | Configures Conventional Commits and concise changelogs. |
.config/cog-changelog.tera | Renders plain Markdown changelogs without author noise. |
scripts/setup-tooling.py | Resolves the lock, installs tools, installs hk hooks, and returns JSON status. |
scripts/enable-docs-deployment.py | Configures workflow-built Pages through external gh. |
skills/dstack-core/scripts/reconcile-beads-interactions.py | Verifies and reconciles append-only Beads interaction evidence. |
skills/dstack-core/scripts/beads-workflow-lock.py | Serializes dstack Beads mutation intervals outside Git. |
skills/dstack-core/scripts/finalize-feature-delivery.py | Guards delivery/root closure with post-merge evidence. |
.github/workflows/validate.yml | Runs locked mise run check on pushes and pull requests. |
.github/workflows/docs.yml | Builds gated docs from the default branch or manual dispatch. |
Tools
The universal tool set is hk 1.49.0, Node lts, and the latest Cocogitto, Harper CLI, Contextlint, mdBook, uv,
rumdl, typos, and npm:markdown-table-formatter releases. Contextlint checks documentation links, anchors, and image
targets. Its reviewed low-download aube exception applies only to @contextlint/cli. Both hk Pkl imports use 1.49.0.
Equivalent native hk steps own formatter and linter commands; independent steps have no explicit depends edges. Custom
steps remain only where behavior differs: Contextlint requires whole-project discovery, documentation is a project
composite, Markdown-table formatting has no built-in, and rumdl avoids a noncanonical built-in diff header.
Recorded language profiles: python.
Commit messages and changelogs
Changelog-visible feat, fix, perf, and refactor commits require a semantic scope. The commit hook also checks
Conventional Commit syntax, grammar, a 72-character subject, 100-character body lines, and canonical optional Beads:
footers. Harper uses its full native rule set after filtering Git comments/diffs, canonical release subjects, and a
canonical Beads: footer; the other commit validators still inspect the unfiltered message. Internal build, chore, CI,
documentation, release, style, and test commits are omitted from cog changelog. Breaking changes render as plain
Markdown.
The generated cog.toml initially accepts any syntactically valid scope. To constrain scopes, add a scopes = ["..."]
allowlist, document each stable subsystem in README when present or on this page otherwise, and update AGENTS.md so
agents apply the same taxonomy. Run cog check after changing the allowlist.
Python profile
| Step | Check | Fix | Files |
|---|---|---|---|
| Ruff lint | ruff check --force-exclude | add --fix | **/*.py, **/*.pyi |
| Ruff format | ruff format --quiet --force-exclude --diff | omit --diff | **/*.py, **/*.pyi |
| ty | ty check | none | **/*.py, **/*.pyi |
| pytest | uv run pytest | none | root pyproject.toml plus tests/**/*.py; check only |
Ruff and ty are mise-managed at latest; pytest is project-owned. The profile ignores .venv/, __pycache__/,
*.py[cod], .pytest_cache/, and .ruff_cache/.
Tasks
| Task | Behavior |
|---|---|
check | Run all hk checks without requesting fixes. |
fix | Apply deterministic hk fixes to the working tree. |
docs:check | Build the book, then validate documentation metadata and navigation. |
docs:build | Build the mdBook site. |
docs:deployment:enable | Configure Pages and enable its repository gate through external gh. |
docs:serve | Serve mdBook on port 3000 by default or a supplied port. |
The committed lock targets linux-x64, linux-arm64, macos-x64, and macos-arm64. Windows is not part of this
POSIX-shell task contract.
The mise environment routes hk hooks through mise with HK_MISE=1 and sets GIT_CONFIG_PARAMETERS="'merge.ff=only'",
so Git rejects merges that require a merge commit.
scripts/check-docs.py is stdlib-only and runs with uv run --no-project python, avoiding a path-keyed uv script
environment. Beads hooks are installed separately by /setup-project after its bd init amend commit and by
/update-project after successful conflict-free tooling. Each workflow verifies bd hooks list --json; the workflow
JSON reports the separate beads_hooks status and recovery commands. Recover missing or outdated Beads hooks with:
bd hooks install
bd hooks list --json
The universal tool count remains ten; gh is an external administrative prerequisite, not a mise tool. Pages requires
build_type=workflow plus DOCS_DEPLOYMENT_ENABLED=true. The build job has contents: read; only the deploy job has
pages: write and id-token: write.
Beads interaction authority is shared across linked worktrees. dstack mutation intervals use the repository-scoped lease
in skills/dstack-core/references/INTERACTION-BOUNDARY.md; the lease is outside Git and is not a replacement for
lineage validation. Foreign rows remain blocking and must be finalized by their owning work unit.
The project provisioner reports separate mise availability, lock, install, and hk hook states. Overall status is
succeeded, degraded, or skipped; failed or skipped stages include exact recovery commands.