AI Agents HQ

Changelog

A chronological record of all significant changes to AI Agents HQ. Each entry includes the date, what changed, and the relevant commits.

Fixes identified during cross-review of the M1 hardening implementation. These changes improve data integrity, error handling, and test coverage.

Bug Fixes:

Fixed description corruption on task complete/fail. Previously, hq task complete --summary and hq task fail --reason appended text to the task's description field, permanently destroying the original instructions. Now completion summaries are stored in a dedicated summary field and failure details in a failureDetail field. The original description is never modified.

Made auto-unblock and sync-blocks best-effort on task complete. Previously, if autoUnblock or syncDerivedBlocks failed after a successful completion (e.g., CAS conflict on a dependent task), the CLI exited non-zero even though the task was already completed and the idempotency key recorded. Now these operations log warnings to stderr but do not fail the completion.

New Features:

Added --notify flag to hq task complete. Optionally sends a task_completed inbox event to a specified agent after successful completion. Uses its own idempotency key (complete-notify:{taskId}:{key}) and is best-effort (warns on failure, does not fail the completion). Example: --notify team-lead

New Task Fields:

summary (*string) — Stores the completion summary from hq task complete --summary. Replaces the old behavior of appending to description.
failureDetail (*string) — Stores the failure reason text from hq task fail --reason. Replaces the old behavior of appending to description.

New Tests (7 added):

TestIntegration_DescriptionPreservedAfterComplete — Verifies description unchanged after completion, summary field populated
TestIntegration_DescriptionPreservedAfterFail — Verifies description unchanged after failure, failureDetail field populated
TestIntegration_StaleLeaseClaim — Manually expires lease, verifies different agent can reclaim
TestIntegration_CompleteWithNotify — Verifies --notify creates inbox event for target agent
TestIntegration_ConcurrentInboxSendsMonotonicIDs — 8 concurrent sends, verifies strictly monotonic event IDs
TestIntegration_FlagParsingEdgeCases — Table-driven test with 8 cases covering missing/malformed args across all commands
TestIntegration_CompleteUnauthorizedDoesNotConsumeIdempotencyKey — Validates 3-step flow (unauthorized fail, authorized succeed, retry no-op)

Files Changed:

internal/teams/protocol/task_schema.go — Added Summary and FailureDetail fields to Task struct
cmd/hq/task_cmd.go — Fixed description corruption, made auto-unblock best-effort, added --notify flag
cmd/hq/command_helpers.go — Added mustMarshalString helper for safe JSON string encoding
cmd/hq/integration_test.go — Added 7 new integration tests

Hardened the coordination core with deterministic exit codes, identifier validation, atomic task creation, and improved test coverage.

Commits: bdf81f2, 2400977

Changes:

Added deterministic CLI exit codes using sentinel error pattern (errValidation, errStaleLease, errProtocolMismatch) with commandExitCode() switch mapping errors to exit codes 0, 10-14
Added identifier validation with safeIdentifierPattern regex — team and agent names must match [A-Za-z0-9._-]+
Added atomic task ID allocation with .nextid lock file to prevent race conditions during hq task create
Split idempotency into HasKey() (read-only check) and CheckAndSet() (atomic set) for correct ordering in completion flow
Added ReadFile() permission enforcement — files with insecure permissions (group/other readable) are rejected with exit 14
Added syncDerivedBlocks() for full recompute of blocks arrays from blockedBy data
Added inbox event type validation against ValidInboxEventTypes map
Added command_helpers.go with shared CLI utilities (flag parsing, validation, exit code mapping)

Updated all Codex profiles from legacy models to codex-optimized variants and expanded Codex role to include implementation partner.

Commits: d65928c

Changes:

Default Codex model updated to gpt-5.3-codex (77.3% Terminal-Bench, 77.6% Cybersec CTF)
Reviewer and security-auditor profiles upgraded to gpt-5.3-codex with xhigh reasoning
Quick-fix profile upgraded from gpt-4.1 to gpt-5.1-codex-mini
Codex role expanded from "QA Lead" to include "Implementation Partner" for cross-model auditing
Gemini auto-routing enabled (removed model pin from settings.json)

Commits: b0d822e, 86f9237

Instruction files, agent definitions, skill templates, and tool configurations for all three CLI tools.

Commits: defeebe, 9bc5ebe, ed67f7b, 0c671f4, dd35e5f

Changes:

Added CLAUDE.md (Lead Developer), GEMINI.md (Research Specialist), AGENTS.md (QA Lead & Implementation Partner)
Added .gemini/settings.json with auto-routing, agents enabled, write tools excluded
Added .codex/config.toml with 5 profiles (reviewer, security-auditor, git-expert, refactor, quick-fix)
Added 4 Claude subagents (researcher, reviewer, architect, optimizer)
Added 2 Gemini subagents (deep-researcher, api-auditor)
Added 5 Claude skills (research, refactor, test-writer, code-review, team-protocol)
Added 3 Gemini skills (deep-research, api-audit, team-protocol)
Added 5 shared agent templates and 5 shared skill templates

The protocol, storage, and CLI foundation for multi-agent task coordination.

Commits: faac95b, da094ba

Changes:

Added protocol constants: exit codes (0, 10-14), task statuses (6 states), state reasons (6 codes), inbox event types (5 types), protocol version 2, schema version 1
Added Task struct with 22 fields, CAS versioning, lease management, validation
Added Inbox struct with append-only events, monotonic IDs, idempotency keys
Added file locking via flock(2) system call
Added atomic writes via tmp-fsync-rename pattern
Added persistent idempotency key store
Added TaskStore with CRUD, list, atomic ID allocation, UpdateWithLock with CAS
Added InboxStore with send (idempotent), read (with since-event filter)
Added hq CLI with 8 commands: task create/list/claim/complete/fail/heartbeat, inbox send/read
57 tests passing (26 protocol + 17 storage + 14 integration)

Project reset from v1 prototype to clean Go project structure.

Commits: 3d1ded2, 5b1db52

Changes:

Archived v1 prototype to archive/v1-prototype branch
Cleaned main branch, created Go module (github.com/gbas/ai-agents-hq)
Created directory structure: cmd/hq/, internal/teams/protocol/, internal/teams/storage/
Added CI pipeline with 3 gates: gofmt check, golangci-lint, go test with race detector
Added CLAUDE.md with architecture context and build commands