hal-command-surface.md

MQLaunch HAL Command Surface

This document describes the mqlaunch hal command surface.

mqlaunch owns the terminal UX. mq-hal owns HAL logic.

The bridge lives here:

terminal/bridges/hal-bridge.sh

The interactive HAL menu lives here:

terminal/menus/mq-hal-menu.sh

---

Core Rule

The HAL menu must preserve the MQLaunch surface layout.

Expected layout primitives:

surface_panel_header
surface_row
surface_split_row
surface_bottom
read_main_choice "hal"

Do not replace the HAL menu with custom printf layout unless intentionally redesigning all MQLaunch menus.

---

Command Groups

Observe

Read-only status and quality commands.

mqlaunch hal brief
mqlaunch hal audit
mqlaunch hal release-brief
mqlaunch hal repo-status
mqlaunch hal ci
mqlaunch hal doctor
mqlaunch hal timeline
mqlaunch hal timeline --details

Plan

Commands that produce safe next-step plans.

mqlaunch hal fix-doctor

Memory

Commands that read or write local HAL memory.

mqlaunch hal session
mqlaunch hal last
mqlaunch hal remember "note"
mqlaunch hal memory-path

Debug

Commands for routing/debugging.

mqlaunch hal repos
mqlaunch hal cd macos-scripts
mqlaunch hal raw "kor doctor"
mqlaunch hal "visa git status"

---

Command Reference

Command	Backend	Type	Purpose
mqlaunch hal	mq-hal-menu.sh	menu	Opens interactive HAL menu
mqlaunch hal brief	mq-hal brief	read-only	Compact repo status snapshot
mqlaunch hal audit	mq-hal audit	read-only	Publish/readme quality audit via repo-signal
mqlaunch hal release-brief	mq-hal release-brief	read-only	Release readiness summary
mqlaunch hal repo-status	mq-hal repo-status	read-only	Git repo status, commits, tags
mqlaunch hal ci	mq-hal ci	read-only	GitHub Actions status
mqlaunch hal doctor	mq-hal doctor-summary	read-only	Doctor summary
mqlaunch hal fix-doctor	mq-hal fix-doctor	planning	Safe manual fix plan
mqlaunch hal timeline	mq-hal timeline	read-only	Local HAL memory timeline
mqlaunch hal session	mq-hal session	read-only	Local HAL session memory
mqlaunch hal last	mq-hal last	read-only	Latest memory item
mqlaunch hal remember "note"	mq-hal remember "note"	memory-write	Saves local note
mqlaunch hal repos	mq-hal --list-repos	read-only	Lists configured repos
mqlaunch hal cd <repo>	mq-hal --cd <repo>	read-only	Prints repo path
mqlaunch hal raw "prompt"	mq-hal --raw-intent "prompt"	debug	Shows parsed JSON intent
mqlaunch hal "prompt"	mq-hal "prompt"	routed	Free HAL prompt

---

Safety Model

HAL commands should follow this rule:

observe first
plan second
manual execution last

Allowed behavior:

read status
summarize output
show recommendations
print safe commands
write local notes only when explicitly requested

Disallowed behavior:

auto-delete
auto-reset
auto-commit
auto-push
auto-release
auto-submit
run arbitrary shell from model output

---

Release Checklist

Before releasing HAL changes in macos-scripts:

bash -n terminal/bridges/hal-bridge.sh
bash -n terminal/menus/mq-hal-menu.sh
bash -n terminal/launchers/mqlaunch-command-mode.sh
zsh -n terminal/launchers/mqlaunch.sh

./tests/hal-menu-smoke.sh
./tests/hal-menu-layout-smoke.sh
./tests/hal-command-surface-smoke.sh
./tests/hal-format-smoke.sh

mqlaunch hal help
mqlaunch hal audit --sample
mqlaunch hal brief --sample
mqlaunch hal release-brief --sample
mqlaunch hal repo-status --sample
mqlaunch hal ci --sample

mqlaunch selftest
mqlaunch doctor --json | jq .
mqlaunch release-check

---

Definition Of Done

A HAL bridge/menu change is complete when:

bridge route exists
menu item exists if interactive
layout smoke test passes
format smoke test passes
command surface docs updated
README references command surface
COMMANDS.md references command surface
VERSION and CHANGELOG updated
CI is green
release notes exist