Engineering playbook

Choose the task below, read its scope and prerequisites, then run the linked commands from the repository root. The workflow catalog records which checks run locally and which require Actions. Use the shared task registry for local, Ansible and hosted Lua operations. Workflow events, permissions, protected publication and human approval retain their GitHub authority.

Task	Procedure or rule	Execution guide	Status
Prepare a development checkout	Toolchain	Development setup	Existing tools and local checks.
Define and approve SDD work	Specification issues	Label commands	Maintainer approval; hosted reconciliation after activation.
Implement and review a change	Change procedure	Local checks	Proposed wider procedure; implemented checks.
Review an engineering choice	Review procedure	Verification	Rationale and evidence in the issue or pull request.
Check documentation	Authoring and validation	Documentation commands	Implemented.
Exercise process evidence	Evidence contract	Local process pilot	Four scoped controls and requirement evidence, local and CI.
Build supported profiles	CI reference	Build runbook	Mock build matrix.
Verify a candidate	Verification procedure	Qualification, C analysis	Mock campaigns.
Compare independent builds	Reproducible-build assurance	Reproducibility	Declared tool campaigns.
Prepare a release	Release procedure	Release fixture	Mock fixture; protected publication.
Configure security services	Security procedure	Service bootstrap	Service-specific prerequisites.
Review assurance gaps	Framework mappings	OpenSSF plan, gaps	Proposed assessments.

On this page

Run a registered task
Clean disposable state
Pilot requirement

Run a registered task

Inspect the task registry with the native root playbook:

Use native Ansible after installing it once on the machine. The playbook checks host prerequisites, prepares or repairs the Lua runtime and installs the selected task profile on normal runs. No environment activation is required. Campaign-specific inputs and credentials retain the prerequisites listed below:

ansible-playbook playbook.yml
ansible-playbook playbook.yml -e lma_task=doctor
ansible-playbook playbook.yml -e lma_task=docs-build
ansible-playbook playbook.yml --check -e lma_task=spec-labels

Follow workspace setup for automatic preparation profiles and host prerequisites. Normal runs activate the repository Git configuration automatically. Check mode does not write Git settings; repair and uninstall tasks retain their own behavior. Nix shells provide host tools. Pass domain arguments as the ordered lma_arguments list. Check mode validates the CLI contract and displays the complete literal argument vector without running the domain operation. Unknown options, duplicate options, missing values and supported domain-value constraints fail before Git setup or task execution. Planning does not validate credentials, tool availability or the contents of future evidence files. Verification tasks report no changes. Mutating commands report their observed changes separately from their declared effects, so repeating an unchanged setup or cleanup reports changed=0. The supervisor retains per-task logs and JSON/JUnit results with timeout and child-exit information.

Playbook action	Registered task family	Prerequisites and contract
Validate specification plans	sdd-check, sdd-test	SDD validation
Validate or build docs	docs-check, docs-eval, docs-build	Documentation tools
Prepare Nix tools	nix-setup	Nix environment; skips hosts without Nix
Generate tool manifests	toolchain-sync	Central version policy
Prepare a checkout	setup, status, setup-repair, setup-uninstall	Git configuration and hooks
Clean generated state	clean	Cleanup scopes; preserves installed tools
Test Ansible integration	ansible-test	Workspace controller
Test automation	tests	Self-contained suites
Check a checkout	checks, lua-check	Local checks
Maintain specification labels	spec-labels, spec-reconcile	Maintainer authority
Build and reconstruct locally	build	CMake profiles
Build a profile	build-plan, build-run, build-report	Build campaign
Verify a candidate	qualification-plan, qualification-run, qualification-report, analysis	Qualification, analysis
Compare rebuilds	reproducible-prepare, reproducible-vary	Reproducibility
Construct and verify a fixture	release-build, release-verify	Release fixture
Exercise security adapters	security-plan, security-run, security-report	Security integrations
Exercise process evidence	process-ci, process-plan, process-run, process-gate, process-report	Process pilot

The workflow task catalog extends the registry with the existing CI commands for provisioning, validation, packaging, analysis and reporting. Discover exact names and contracts:

lua scripts/process/playbook.lua list
lua scripts/process/playbook.lua describe check-lua
lua scripts/process/playbook.lua plan build --profile=debug --jobs=4
lua scripts/process/playbook.lua --direct check-lua

Normal Lua dispatch and Ansible use the bounded supervisor and retain task logs. Hosted workflows use --direct so child stdout remains suitable for GITHUB_OUTPUT and command substitution; the exact child exit code propagates. Their job timeouts and domain reports supply the execution boundary. Both modes resolve the same static command prefixes and preserve literal argument boundaries. Unknown tasks fail. Lua listing and planning perform no setup; native Ansible prepares a missing runtime before listing. CLI contracts live in tools/process/arguments.lua and the argument validator; update them when a registered command's CLI changes. Ansible consumes the supervisor's structured result using --result-json. Its change_status is changed, unchanged or unknown; an unreported mutation is explicitly unknown, never inferred from the task category. Domain commands use scripts/lib/change.lua to report changes without decorating their normal output. A task's diagnostic files are separate from its domain change count. An unknown outcome conservatively counts as changed in the Ansible recap and prints an explicit explanation; the JSON retains unknown. Failed mutating tasks cannot confirm a no-op. Python provisioning compares installed entries before and after synchronization, so a repeated unchanged environment reports no domain change.

Bootstrap, third-party Actions, artifact transport, OIDC and protected deployment remain native workflow steps. The registry consolidates owned Lua operations and does not grant credentials or bypass approval. The playbook regression suite checks registered workflow references, both dispatch modes and literal argv. Use quality-setup to install locked tools and lua-check for the measured Lua gate.

The task registry selects commands; a successful task does not establish release acceptance or framework conformance. Keep decisions, SDD approval and protected deployment in their reviewed workflows.

Clean disposable state

Preview and execute cleanup through the same task registry:

ansible-playbook playbook.yml --check -e lma_task=clean
ansible-playbook playbook.yml -e lma_task=clean
ansible-playbook playbook.yml -e lma_task=clean \
  -e '{"lma_arguments":["--scope=temporary"]}'

The Lua entrypoints also work without an Ansible controller:

lua scripts/process/playbook.lua plan clean --scope=all
lua scripts/process/playbook.lua --direct clean --dry-run
lua scripts/process/playbook.lua clean --scope=build

Scope	Disposable paths below .cache/
build	build, install, docs, metadata, ci, cd, logs, validation
cache	downloads, tools/uv-cache, tools/npm, tools/pip, tools/ruff, tools/go-build, tools/xdg
temporary	tmp, tests
all	All three scopes; the default

Cleanup removes build metadata together with its build tree. Installed tools, bootstrap receipts, tools/automation.yml, live Ansible temporary state, Git data and sources remain available. The supervised command retains cleanup receipts under .cache/cleanup/, so a repeated full cleanup can remain unchanged. Unknown directories are preserved. On Linux and macOS, ordinary playbook execution and build controllers hold a shared kernel lease. Linux uses util-linux flock; macOS uses Python fcntl.flock. Cleanup, automation bootstrap and quality installation require an exclusive lease, protecting executables from replacement while tasks use them. Conflicting commands fail immediately with exit code 75 before their task starts. Retry after the active task finishes. The kernel releases leases when their owners exit, including after a crash. .cache/locks/ is preserved and must not be removed while commands are running.

Commands launched directly with external tools must join the same protocol, for example:

lua scripts/workspace/with_lock.lua -- cmake --build .cache/build/example

Cleanup supports Linux and native macOS. The workspace lease does not coordinate other machines or raw commands that bypass the wrapper.

--dry-run lists targets without removing them. Cleanup rejects tracked cache files, symlinked parent directories and mounted child directories; links inside disposable trees are unlinked without following them. Planning validates the complete selection, and execution repeats that validation before its first deletion. Repeated cleanup reports no domain change when the selected paths are already empty.

Pilot requirement

The canonical LMA-ENG-001 requirement, its four Lua commands and the Ansible invocations now live in the process pilot runbook. Only the local profile is implemented. Its passing gate records promotion_authorized: false and product_qualified: false.