Skip to content

Roadmap

Jump to bottom
McAmner edited this page Jun 2, 2026 · 1 revision

mq-hal Roadmap

mq-hal is a local HAL-style command router for the mq ecosystem.

It turns natural-language prompts into structured JSON intents through a local model, then lets a safe Python router decide what is allowed.

The model never runs shell directly.

user prompt
  ↓
Ollama / Qwen
  ↓
JSON intent
  ↓
safe Python router
  ↓
allowlisted git / repo / mqlaunch / helper actions

mq-hal should feel like a local HAL assistant, but behave like a controlled command router.

In the mq ecosystem, mq-hal is the operator/status layer. It summarizes local state, diagnostics and readiness. It should not orchestrate mq-agent or own mq-mcp execution/review logic.

It should be:

  • local-first
  • explicit
  • safe by default
  • deterministic when needed
  • testable
  • mqlaunch-friendly
  • repo-aware
  • memory-aware
  • useful without hiding execution

Current status

Latest stable release:

v1.2.0 — vector-store health summary in stack-status

Completed foundation:

  • local natural-language command routing
  • Ollama/Qwen intent generation + model profiles
  • JSON intent schema (v1, formally validated)
  • safe Python router + intent allowlist
  • whitelisted command execution
  • deterministic no-AI fallback
  • repo config
  • repo status and CI status
  • HAL brief, release brief, audit
  • HAL stack status + mq-agent integration
  • doctor summary and fix planner
  • session memory and timeline
  • mqlaunch HAL bridge
  • README markdown guard + release-check gate
  • GitHub Pages docs
  • Advanced Ollama Runtime: plan, critic, execute, tools, models
  • Visual HAL: analyze-diagram, review-ui, architecture-brief
  • Packaged install/update flow + release gate v2
  • Learn layer with secret redaction

Current recommended next step:

v1.0.3 — ROADMAP cleanup

Release map

Version Theme Status
v0.1.x Public baseline and local routing foundation Done
v0.6.0 Notifications Done
v0.8.x Doctor summary and fix planner Done
v0.9.x Audit, release brief, repo ops, session and timeline Done
v0.10.0 HAL Stack Status Done
v0.10.1 Version sync, CI coverage and release-check Done
v0.11.0 Intent contract and command-surface hardening Done
v0.12.0 mq-agent and semantic memory integration Done
v0.13.0 Bridget/HAL interaction polish Done
v0.14.0 Advanced Ollama Runtime Done
v0.14.5 Visual HAL Done
v0.15.x Packaged install, update flow and release gate v2 Done
v1.0.0 Stable local HAL command router Done
v1.0.1 HAL Learn Layer Done
v1.0.2 Runtime observability: env-status Done
v1.0.3 ROADMAP cleanup — all stale items resolved Done
v1.1.0 mq-mcp runtime health observability in stack-status Done
v1.2.0 Vector-store health summary in stack-status Done

Completed

v0.1.x — Public baseline and local routing foundation

Goal:

Create the first local HAL-style router with safe command boundaries.

  • Create repository
  • Add README
  • Add LICENSE
  • Add CHANGELOG
  • Add VERSION
  • Add ROADMAP
  • Add GitHub Pages docs
  • Add local wrapper command
  • Add repo config
  • Add initial natural-language routing
  • Add Ollama/Qwen model integration
  • Add JSON intent output
  • Add safe Python router
  • Add command allowlist
  • Add deterministic fallback path
  • Add initial tests and smoke checks

v0.6.0 — Notifications

Goal:

Make longer-running local commands easier to notice.

  • Add macOS desktop notification support
  • Use osascript for local notifications
  • Keep notification behavior local
  • Avoid notification dependency for core routing

v0.8.x — Doctor summary and fix planner

Goal:

Turn local system health output into safe, readable HAL summaries.

  • Add mq-hal doctor-summary
  • Add mq-hal doctor-summary --json
  • Add mq-hal doctor-summary --no-ai
  • Parse mqlaunch doctor --json
  • Summarize doctor output with Ollama when available
  • Fall back to deterministic local summaries
  • Add mq-hal fix-doctor
  • Add mq-hal fix-doctor --json
  • Add mq-hal fix-doctor --no-ai
  • Print copy-paste repair plans
  • Execute nothing from fix planner automatically

v0.9.x — Audit, release brief, repo ops, session and timeline

Goal:

Make mq-hal useful for real repo/release operations while staying safe.

  • Add mq-hal audit
  • Add mq-hal audit --json
  • Add repo-signal publish quality check
  • Add repo-signal README score check
  • Add mq-hal release-brief
  • Add mq-hal release-brief --json
  • Check VERSION
  • Check CHANGELOG entry
  • Check README version badge/reference
  • Check git clean/dirty state
  • Check recent CI status
  • Check latest GitHub release
  • Check doctor summary
  • Check release-check status
  • Add mq-hal repo-status
  • Add mq-hal ci
  • Add mq-hal session
  • Add mq-hal last
  • Add mq-hal remember
  • Add local session memory in ~/.mq-hal/session.jsonl
  • Add mq-hal timeline
  • Add timeline filters
  • Add timeline JSON output
  • Add README markdown guard
  • Add smoke tests for HAL commands

v0.10.0 — HAL Stack Status

Goal:

Show the local mq/HAL toolchain state in one read-only command.

  • Add mq-hal stack-status
  • Add mq-hal stack-status --json
  • Add mq-hal stack-status --sample
  • Check mq-hal wrapper
  • Check mqlaunch availability
  • Check repo-signal availability
  • Check optional Bridget availability
  • Check configured repo paths
  • Check git branch and dirty state
  • Check VERSION file
  • Check repo-signal publish checklist when available
  • Add tests/stack-status-smoke.sh
  • Document Stack Status in README
  • Document Stack Status in command surface docs

v0.10.1 — Version sync, CI coverage and release-check

Goal:

Make release readiness verifiable before adding more HAL features.

  • Sync GitHub Pages version with VERSION
  • Add HAL router smoke test to CI
  • Add Proof section to README
  • Add release-check.sh
  • Check Python syntax
  • Check markdown guard
  • Check version sync
  • Check smoke tests
  • Extend docs smoke test
  • Verify docs/index.html version matches VERSION
  • Run CI on macos-latest
  • Verify smoke tests natively on macOS

v0.11.0 — Intent contract and command-surface hardening

Goal:

Make mq-hal's routed command surface explicit, testable and stable enough for mqlaunch, mq-agent and future HAL workflows to depend on.

Scope

  • Add docs/INTENT_CONTRACT.md
  • Add docs/COMMAND_SURFACE.md or refresh existing command surface docs
  • Define canonical intent schema version
  • Add intent version field
  • Document every intent type
  • Document every allowed action
  • Document required fields per intent
  • Document optional fields per intent
  • Document rejected/unknown intent behavior
  • Document no-AI deterministic fallback behavior
  • Add examples of valid intents
  • Add examples of rejected intents
  • Add command-count guard
  • Add intent-schema smoke test
  • Add router allowlist smoke test
  • Add docs consistency check for command surface
  • Add release-check section for intent contract
  • Update README with intent contract proof
  • Update GitHub Pages with v0.11.0 status

Proposed intent schema

{
  "schema_version": "1",
  "action": "repo_status",
  "repo": "macos-scripts",
  "path": null,
  "args": {},
  "requires_confirmation": false,
  "safety_class": "read-only"
}

Proposed safety classes

read-only
repo-read
repo-search
repo-write-preview
mqlaunch-allowlisted
doctor-summary
fix-plan-only
session-write
notification
unknown
rejected

Commands to verify

mq-hal --raw-intent "visa git status i macos-scripts"
mq-hal --explain-intent "hitta OLLAMA_MODEL i mq-hal"
mq-hal --confirm "kör tester i mq-hal"
mq-hal repo-status --json
mq-hal ci --json
mq-hal brief --json
mq-hal release-brief --json
mq-hal audit --json
mq-hal stack-status --json

Structured Intent Engine

  • Move intent contract to formal JSON Schema
  • Add schemas/intent.schema.json
  • Validate all model output before routing
  • Reject malformed intents
  • Reject unknown actions
  • Add intent risk classification
  • Add rollback-plan field
  • Add requires-confirmation field
  • Add intent contract examples
  • Add intent contract tests

Definition of done

  • Intent schema is documented
  • Intent schema has a version field
  • Unknown intents are refused
  • Unsafe intents are refused
  • All allowed actions are documented
  • All mqlaunch delegated commands are documented
  • Command-surface docs match README
  • Intent examples are tested
  • Router smoke tests pass
  • Docs smoke tests pass
  • release-check.sh passes
  • GitHub Actions pass
  • GitHub release v0.11.0 exists

Carried forward to v0.14.0

These items were not completed and are required before or during v0.14.0:

  • GitHub Actions pass on main
  • Add intent risk classification to intent schema
  • Add rollback-plan field to intent schema
  • Add requires-confirmation field to intent schema
  • No new command merged without a corresponding router test

v0.12.0 — mq-agent and semantic memory integration

Goal:

Make mq-hal a stronger reasoning/status layer for mq-agent and semantic repo memory workflows.

Boundary:

mq-hal summarizes status.
mq-agent orchestrates.
mq-mcp executes, reviews and owns memory/reasoning runtime.

Planned scope

  • Add mq-hal memory-status
  • Add mq-hal memory-brief
  • Add mq-hal agent-brief
  • Summarize mq-agent memory status
  • Summarize repo-signal semantic upload state
  • Include semantic memory state in mq-hal brief
  • Include semantic memory state in mq-hal release-brief
  • Add mq-agent status to mq-hal stack-status
  • Add mq-mcp runtime health, vector health and model health to stack summaries
  • Add docs for mq-agent integration
  • Add smoke test for mq-hal → mq-agent
  • Add smoke test for mqlaunch → mq-hal → mq-agent
  • Add fallback behavior if mq-agent is missing

Boundary rules

  • mq-hal may display mq-agent availability and mq-mcp health in summaries
  • mq-hal may call read-only status/report commands
  • mq-hal must not route review execution around mq-agent
  • mq-hal must not implement mq-mcp review, risk or semantic-memory logic

Repo Memory

  • Add repo indexing (mq-hal index <repo>)
  • Add optional Ollama embeddings support (mq-hal index <repo> --embeddings)
  • Add memory search
  • Add repo-aware retrieval
  • Add repo-map generation
  • Add architecture knowledge extraction
  • Add roadmap knowledge extraction
  • Add release-history knowledge extraction

Possible commands

mq-hal memory-status
mq-hal memory-brief
mq-hal agent-brief
mq-hal stack-status --include-agent
mq-hal index <repo>
mq-hal search <query>
mq-hal ask-repo <question>
mq-hal repo-map

Example target flow

mqlaunch
  ↓
mq-hal
  ↓
mq-agent
  ↓
repo-signal semantic memory

Non-goals

  • No silent memory upload
  • No hidden OpenAI API calls
  • No destructive agent actions
  • No automatic repo mutation

Carried forward to v0.14.0

  • mq-mcp runtime health, vector health and model health in stack-status
  • mq-hal index <repo> — local repo indexing
  • Ollama embeddings support
  • mq-hal search <query> — memory search
  • mq-hal ask-repo <question> — repo-aware retrieval
  • mq-hal repo-map — repo-map generation
  • Architecture, roadmap and release-history knowledge extraction

v0.13.0 — Bridget/HAL interaction polish

Goal:

Make the HAL experience feel clearer, more memorable and easier to use without weakening the safety model.

Planned scope

  • Improve Bridget/HAL identity docs
  • Add optional HAL greeting/status screen
  • Add clearer terminal output sections
  • Add compact and verbose output modes
  • Add better timeline formatting
  • Add better session summaries
  • Add optional voice-mode design doc
  • Add toggle design for Bridget voice
  • Add local-only voice safety notes
  • Add screenshot or terminal demo

Possible commands

mq-hal hello
mq-hal status-screen
mq-hal timeline --compact
mq-hal timeline --details

Non-goals

  • No cloud voice dependency by default
  • No hidden recording
  • No always-on listener
  • No voice command execution without confirmation

Carried forward to v0.14.0

  • Add better session summaries (grouped by type, counts)

Carried forward to v0.15.0

  • Add screenshot or ASCII terminal demo

Before v0.14.0 — Stabilization gate

Do not add more commands or merge new features until all items below are satisfied.

This gate exists because the constraint "AI may propose intent, the router decides what is allowed" must be verifiably true before the runtime layer gets more powerful.

Version sync (satisfied ✓)

  • VERSION = 0.13.0
  • README badge = 0.13.0
  • CHANGELOG entry for 0.13.0
  • GitHub release v0.13.0 exists

Safety infrastructure (satisfied ✓)

  • schemas/intent.schema.json — formal intent schema
  • tests/intent-schema-smoke.sh — schema/code parity enforced
  • tests/router-safety-smoke.sh — allowlist boundary tested
  • docs/COMMAND_SURFACE.md — canonical command registry
  • tools/check-command-docs.sh — command docs enforced in release

Remaining before v0.14.0

  • GitHub branch protection on main: require CI success, block force push
  • GitHub Actions green on main
  • docs/INTEGRATION.md integration boundary describes current role division clearly
  • All carried-forward items from v0.11.0, v0.12.0, v0.13.0 are triaged: each is either scheduled for v0.14.0 or explicitly deferred

Rule

No new commands are merged before CI is green and branch protection is active on main.

v0.14.0 — Advanced Ollama Runtime

Goal:

Turn mq-hal into a structured local reasoning layer while preserving strict execution safety.

Planned scope

Tool Registry

  • Add mq_hal/tools/ directory with tool modules
  • Add tool metadata schema (name, description, input_schema, risk_level, requires_confirm)
  • Add tool capability discovery
  • Add tool-call validation
  • Add mq-hal tools and mq-hal tools --json

Planner

  • Add mq-hal plan "<goal>" mode
  • Output: Goal, Affected repos, Affected files, Risk, Steps, Validation, Rollback

Critic

  • Add mq-hal critic plan.json mode
  • Critic checks: missing tests, over-broad changes, shell execution risk, missing rollback, wrong repo, wrong release flow

Execute

  • Add mq-hal execute plan.json --confirm
  • Execution only after policy check and explicit confirmation

Model Profiles

  • Add config/models.json
  • Add router model profile (e.g. qwen3:4b-instruct, reasoning_effort: low)
  • Add planner model profile (e.g. qwen3:8b, reasoning_effort: medium)
  • Add critic model profile (e.g. qwen3:8b, reasoning_effort: high)
  • Add code-review model profile (e.g. qwen2.5-coder:7b, reasoning_effort: medium)
  • Add model selection CLI support

Model hardening

  • Add model availability check
  • Add model latency measurement
  • Add model response validation
  • Add better fallback to deterministic routing
  • Add prompt regression tests
  • Add invalid JSON recovery tests
  • Add reasoning effort profiles
  • Keep generation non-streaming for structured JSON enforcement
  • Add structured outputs enforcement

Possible commands

mq-hal plan
mq-hal critic
mq-hal explain
mq-hal tools
mq-hal models
mq-hal model-status
mq-hal model-test

Deferred carry-forward gaps

These were reviewed during v0.14.0 and intentionally kept outside the Advanced Ollama Runtime scope:

  • GitHub Actions pass on main (from v0.11.0)
  • intent risk classification in intent schema (from v0.11.0)
  • rollback-plan field in intent schema (from v0.11.0)
  • requires-confirmation field in intent schema (from v0.11.0)
  • No new command merged without a router/smoke test (from v0.11.0)
  • mq-mcp runtime health in stack-status (Runtime observability layer)
  • Repo Memory: index, search, ask-repo, repo-map (from v0.12.0)
  • Better session summaries (from v0.13.0)

Safety rules

  • Models never execute shell directly
  • Router remains authoritative
  • Tool calls must be validated
  • High-risk operations require confirmation
  • Unsafe actions are rejected
  • Model choice must not bypass router safety

v0.14.5 — Visual HAL

Goal:

Connect mq-image-analyze vision capabilities to mq-hal for architecture and UI reasoning.

Planned scope

  • Add mq-hal analyze-diagram <file>
  • Add mq-hal review-ui <file>
  • Add mq-hal architecture-brief <file>
  • Architecture observations
  • Trust-boundary detection
  • YAML draft generation from diagrams
  • UI critique output

Possible commands

mq-hal analyze-diagram architecture.png
mq-hal review-ui screenshot.png
mq-hal architecture-brief

Safety requirements

  • Vision input must never trigger shell execution
  • Output is always read-only observation or draft YAML, never executable intent

v0.15.0 — Packaged install and update flow

Goal:

Make mq-hal easier to install and maintain on a new macOS machine.

Planned scope

  • Add install script
  • Add uninstall script
  • Add upgrade script
  • Add shell completion notes
  • Add PATH setup docs
  • Add mq-hal doctor
  • Add mq-hal version
  • Add config validation command
  • Add clean reinstall docs
  • Add optional Homebrew formula plan

Possible commands

mq-hal version
mq-hal doctor
mq-hal config-check
mq-hal update

Release gate v2

Make release a system check, not just a version bump:

  • release-check.sh blocks release if VERSION, README, CHANGELOG, and GitHub release tag do not all match
  • release-check.sh blocks release if any undocumented command exists in the registry
  • release-check.sh blocks release if any router safety test fails
  • release-check.sh supports --dry-run

Non-goals

  • No hidden daemon
  • No automatic startup without user choice
  • No silent model download
  • No credential handling

v1.0.0 — Stable local HAL command router

Goal:

Make mq-hal stable enough to be the default local HAL command router for the mq ecosystem.

v1.0.0 requirements

  • Stable CLI command surface — 33 commands, enforced by release-check
  • Stable intent schema — schemas/intent.schema.json v1, validated in CI
  • Stable router allowlist — ALLOWED_INTENTS in hal.py, documented in INTENT_CONTRACT.md
  • Stable repo config format — documented in docs/FORMATS.md
  • Stable session memory format — documented in docs/FORMATS.md
  • Stable timeline output — documented in docs/FORMATS.md
  • Stable mqlaunch integration — documented in INTEGRATION.md
  • Stable mq-agent integration — documented in INTEGRATION.md
  • Stable model fallback behavior — model profiles in config/models.json
  • Complete command docs — docs/COMMAND_SURFACE.md + docs/hal-command-surface.md
  • Complete safety docs — docs/INTENT_CONTRACT.md
  • Complete troubleshooting docs — docs/TROUBLESHOOTING.md
  • Complete smoke tests — 29 smoke test files, all passing in CI
  • Complete release-check — GitHub tag gate, undocumented-command gate, safety gate
  • Green CI — GitHub Actions passing on main
  • Protected main branch — branch protection active on main
  • GitHub release — v1.0.0 released
  • GitHub Pages documentation — auto-deployed from main
  • No known critical safety gaps — audited: no shell=True, no os.system, intent output normalized before routing, path escape protection via is_within(), executor validate_command + critic gate + dry-run default. Critic is pattern-based (not allowlist); cat-style reads return REVIEW not FAIL — user sees them in dry-run and must confirm. Design decision.

Future: Runtime observability layer

Goal:

Keep mq-hal focused on runtime health, diagnostics and operator summaries for the mq ecosystem.

This layer should make the stack easier to inspect without becoming the orchestrator.

Planned scope

  • Add mq-mcp runtime health summary — _probe_mq_mcp_http() in stack-status (v1.1.0)
  • Add vector-store health summary — _probe_vector_item_count() in stack-status (v1.2.0)
  • Add model availability and latency summary — mq-hal model-status
  • Add tool availability diagnostics — mq-hal stack-status
  • Add environment-state report with secret redaction — mq-hal env-status
  • Add degraded-mode recommendations — mq-hal env-status

Non-goals

  • No cognition engine
  • No review logic
  • No direct shell execution from model output

Long-term ideas

These are intentionally not scheduled yet.

  • HAL local web dashboard
  • richer terminal UI
  • Bridget voice mode
  • HAL visual timeline
  • repo health history
  • cross-repo release dashboard
  • multi-repo morning brief
  • semantic memory comparison between releases
  • local model benchmark mode
  • safe plugin system
  • team-shared repo config
  • integration with mq-ums
  • integration with mq-mcp safety map
  • integration with repo-signal semantic memory
  • integration with macos-scripts release-check
  • generated architecture diagrams
  • demo videos or GIFs

Design principles

mq-hal should remain:

  • local-first
  • explicit
  • safe by default
  • command-router oriented
  • deterministic when needed
  • JSON-intent based
  • allowlist enforced
  • mqlaunch-friendly
  • repo-aware
  • memory-aware
  • easy to inspect
  • easy to disable
  • useful without hidden automation

HAL should assist the operator.

HAL should not become an unrestricted shell.

Safety principles

mq-hal must never:

  • let the model run shell directly
  • execute unknown intents
  • execute unsafe commands without confirmation
  • mutate repositories invisibly
  • upload memory silently
  • hide command routing
  • ignore repo boundaries
  • print secrets in logs
  • treat AI output as automatically trusted

Every powerful feature must have:

  • dry-run or preview behavior
  • explicit confirmation when needed
  • documented intent shape
  • documented safety class
  • tests
  • fallback behavior
  • failure behavior

Ecosystem role division

Every proposed new HAL command must answer: is this HAL's responsibility, or does it belong in mqlaunch, repo-signal, mq-mcp, or mq-agent?

Repo Role
mq-hal interprets NL, produces status summaries and safe plans
mqlaunch command surface, menus, terminal entrypoint
repo-signal repo quality scoring and publish readiness
mq-mcp MCP tool surface and local tool execution
mq-agent orchestration and larger agent flows

HAL summarizes and plans. It does not replace the other layers.

Governance rules

These rules apply to every release, permanently:

1. The allowlist is the safety boundary — never bypass it.
2. Every new command must answer: is this HAL's responsibility?
3. Intent schema is a contract — unknown intents must be rejected.
4. Command surface must be machine-readable (COMMAND_SURFACE.md).
5. Release is blocked if VERSION, README, CHANGELOG, and CI diverge.
6. Router safety tests must cover unknown intents, path escapes,
   unsafe commands, and confirm flow.
7. No new command merged without a corresponding smoke test.

mq-hal

Clone this wiki locally