AIXCL v1.1.29

AIXCL v1.1.29

Release v1.1.29 -- Agent intelligence package for agentic navigation.

What's New in v1.1.29

Added

• ✅ Agent Cold Start Sequence: AGENTS.md section 0 defines exactly four files to read in order for full orientation, eliminating the previous 5-hop document chain. Closes #1371.
• ✅ Fork Workflow Documentation: AGENTS.md and agent-context.md now document the two-remote setup (origin = upstream, fork = personal) and SSH requirement, preventing the push failures that affected previous agent sessions. Closes #1371.
• ✅ 12 CONTEXT.md Files: High-traffic directories now have agent-readable index files covering purpose, key behavioural notes, agent guidance, and cross-references. Directories covered: lib/aixcl/commands/, lib/core/, lib/cli/, scripts/checks/, scripts/vault/, scripts/runtime/, scripts/security/, services/, vault/agent-config/, tests/command-tests/, .claude/rules/, etc/app-scaffold/. Closes #1371.
• ✅ 5 Architectural Decision Records: docs/architecture/decisions/ documents the five decisions agents repeatedly question or revert: network_mode: host (001), one-shot bootstrap containers (002), VAULT_TOKEN escape hatch (003), topological sort for depends_on (004), and Python3 for YAML parsing (005). Closes #1371.
• ✅ Service Map: docs/reference/service-map.md provides a single table of all 21 platform services with profile membership, port, entrypoint, and health check -- replacing the need to parse docker-compose.yml for an overview. Closes #1371.
• ✅ add-service Skill: .claude/skills/add-service/SKILL.md (and .opencode mirror) provides a 9-step guided checklist for adding a platform service while preserving all invariants. Closes #1371.
• ✅ cut-release Skill: .claude/skills/cut-release/SKILL.md (and .opencode mirror) encodes the full release workflow with dynamic version computation. Closes #1371.
• ✅ Agent Pitfalls Guide: docs/developer/agent-pitfalls.md documents 12 common agent mistakes with corrections -- covering workflow, architecture, vault, and versioning errors. Closes #1371.

Changed

• ✅ docker-compose.yml Invariant Comment: Header comment block explicitly states that network_mode: host and restart: on-failure on bootstrap containers are intentional invariants, with ADR references, to stop repeated reviewer questions. Closes #1371.
• ✅ agent-context.md Extended: .opencode/agents/agent-context.md gains the cold-start sequence, fork remote table, elision check reminder, and references to new ADRs and skills -- while retaining the full context OpenCode agents require. Closes #1371.

Fixed

• ✅ check-agents.sh Arithmetic Bug: ((WARNINGS++)) caused the script to exit on the first warning under set -e (arithmetic expression evaluating to 0 is falsy in bash). Changed to WARNINGS=$((WARNINGS + 1)) so warnings accumulate correctly and only errors cause non-zero exit. Closes #1371.

Documentation

• Getting Started
• Development Workflow
• Changelog

---

Full Changelog: v1.1.28...v1.1.29

AIXCL v1.1.28

AIXCL v1.1.28

Release v1.1.28 -- App CLI robustness, vault bootstrap security hardening, and developer documentation improvements.

What's New in v1.1.28

Added

• ✅ Manifest depends_on Ordering: app start now performs a topological sort of manifest services and starts dependencies first, honoring health checks before starting dependents. Platform services named in depends_on (e.g. ollama) are verified running; unresolvable names and cycles fail with actionable errors. Closes #1332.
• ✅ Compose Diagnostics on Failure: A failing app start or build-on-start now dumps the raw compose output to stderr. New --verbose flag on app start shows full compose and build output on success too. Closes #1337.
• ✅ GPG Signature CI Report: New commit-signature-check.yml workflow reports unsigned or unverified commits pushed to main or dev as non-blocking ::warning:: annotations. Enforcement remains maintainer discipline per DEVELOPMENT.md. Closes #1347.

Changed

• ✅ Vault Bootstrap Agents -- One-Shot: All four vault-agent-*-bootstrap containers converted from restart: unless-stopped with an infinite polling loop to restart: on-failure one-shot containers. Bootstrap scripts exit 0 after a successful secret write; Docker retries only on genuine failure. Root token is no longer held in a long-running container environment after stack startup. Closes #1338.

Fixed

• ✅ Stale Manifest Variables: _app_load_manifest now clears all APP_* variables before applying a new manifest's exports. Previously, loading a second manifest in the same process left stale list entries (services, secrets) from the first, corrupting _app_service_count and service iteration. Closes #1341.
• ✅ Missing TTY for Vault Token Decrypt: _load_vault_token_for_stack short-circuits when VAULT_TOKEN is already set (CI/agent escape hatch). On decrypt failure without a TTY, it now prints actionable options (export VAULT_TOKEN, gpg --pinentry-mode loopback) instead of a hint that cannot work without a terminal. Also fixed a latent bug where GPG_TTY was being set to the literal string not a tty in non-interactive sessions. Closes #1339.
• ✅ Silent Build Skip: Both app build and the build-on-start path now warn when a service declares build configuration (build_context) but built: true is not set, explaining how to enable the build. Closes #1340.

Documentation

• Getting Started
• Development Workflow
• Changelog

---

Full Changelog: v1.1.27...v1.1.28

AIXCL v1.1.27

AIXCL v1.1.27

Release v1.1.27 -- Declarative app provisioning contract for BYO apps, governance consistency fixes, and AI elision guard.

What's New in v1.1.27

Added

• ✅ App Provisioning Contract: New declarative provision: block in app.yaml. The platform idempotently seeds Vault secrets under kv/apps/<name>, renders them to a per-app secrets volume, and creates the PostgreSQL role and database. New ./aixcl app provision and ./aixcl app secrets subcommands; scaffold template includes a commented provision block. (#1331)
• ✅ App Healthcheck Dispatcher: http, cmd, and container_running healthcheck types declared in app.yaml are now honored by app status reporting. (#1336)
• ✅ AI Elision Guard: New scripts/checks/check-ai-elisions.sh detects placeholder text standing in for preserved content and suspicious mass deletions; enforced in CI on every PR and documented in the pre-commit checklist. (#1346)
• ✅ Rules and Skills Mirror Parity Check: check-agents.sh now verifies .claude/ and .opencode/ rules and skills directories are byte-identical. (#1348)
• ✅ Fork Workflow Documentation: New DEVELOPMENT.md section covering fork remotes, local-only overrides, upstream defect capture, and pre-upstream scrub checklist. (#1349)

Changed

• ✅ Per-App Secret Isolation: Apps no longer mount the shared platform secrets volume; each app receives its own aixcl-app-<name>-secrets volume rendered by the platform. Apps never hold Vault tokens. (#1333)
• ✅ App and Platform Demarcation: Removed app-specific bootstrap scripts, Vault agent config, and Prometheus metrics-path hardcoding from platform files; app metrics paths are declared in app.yaml and emitted as __metrics_path__. (#1334, #1335)
• ✅ Escalation Policy Consolidated: DEVELOPMENT.md escalation defers to AGENTS.md Section 7; agents do not create issues unilaterally. (#1344)
• ✅ Label Taxonomy Canonicalized: DEVELOPMENT.md and issue templates aligned to the canonical AGENTS.md taxonomy (Bug/Feature/Task plus required component labels). (#1343)
• ✅ Governance Drift Fixes: ASCII rule scoped to git/CI/web artifacts with Unicode-with-fallback allowance for terminal output; workflow-guard skill corrected; issue templates carry canonical labels. (#1350)

Fixed

• ✅ Static Compliance Self-Attestation Removed: Deleted GOVERNANCE_COMPLIANCE.md; compliance is now enforced mechanically by CI checks instead of asserted in a document. (#1345)
• ✅ Trailing Blank Lines in alerts.yml: Removed trailing blank lines that failed repo-wide yamllint on every PR. (#1353)

Documentation

• Getting Started
• Development Workflow
• Changelog

---

Full Changelog: v1.1.26...v1.1.27

AIXCL v1.1.26

AIXCL v1.1.26

Documentation overhaul, CLI alignment, Unicode cleanup, and username leak remediation.

What's New in v1.1.26

Added

• ✅ App Framework User Guide: Created docs/user/apps.md for the BYO application framework. (#1323)
• ✅ Threat Model Document: Created docs/security/threat-model.md covering threat actors, attack vectors, MITRE ATT&CK mapping, and compensating control cross-references. (#1323)

Changed

• ✅ CLI Help Alignment: Added missing vault command with all 10 subcommands to help_menu(). Renamed utils clean to utils prune and added prune --all. (#1323)
• ✅ AGENTS.md Section Numbering: Fixed broken numbering (now sequential 1-11). (#1323)
• ✅ DEVELOPMENT.md Version Reference: Corrected "AGENTS.md v1.5" to "AGENTS.md v2.0" and fixed Section 8 reference for Emergency Workflow Override. (#1323)
• ✅ Unicode to ASCII Conversion: Replaced all Unicode symbols with markdown checkboxes or plain text across SECURITY.md, modes, and operations docs. (#1323)

Fixed

• ✅ README Step Numbering: Corrected broken Step 4/5 ordering in Quick Start. (#1323)
• ✅ Stale Command References: Replaced non-existent aixcl-setup with ./aixcl stack init, fixed vault passwords to vault credentials, and removed non-existent aixcl security command references. (#1323)
• ✅ Manifest Example: Fixed docs/developer/adding-apps.md YAML example to match actual app_parser.sh flat key format and corrected Prometheus file_sd path. (#1323)
• ✅ Profile Docs: Added missing Alertmanager to bld/sys profile service lists and corrected nvidia-gpu-exporter port from 9400 to 9445. (#1323)
• ✅ Username Leakage: Removed hardcoded sbadakhc references from SECURITY.md, CONTRIBUTING.md, and script usage examples. (#1323)

Documentation

• Getting Started
• Development Workflow
• Changelog

---

Full Changelog: v1.1.25...v1.1.26

AIXCL v1.1.25

AIXCL v1.1.25

Release v1.1.24 -- Vault bootstrap reliability, multi-agent CLI support, and agent governance consolidation.

What's New in v1.1.25

Added

• ✅ Prometheus v3.12.0: Bumped metrics collection from v3.11.1. (#1313)
• ✅ Open WebUI v0.9.6: Bumped web interface from v0.9.5. (#1313)
• ✅ NVIDIA GPU Exporter 1.4.1: Bumped GPU metrics from 1.3.2. (#1313)
• ✅ vLLM v0.22.1: Bumped inference engine alternative from v0.19.0 (version-only, pull_policy: missing). (#1313)
• ✅ Llama.cpp b9585: Bumped inference engine alternative from b8334 (version-only, pull_policy: missing). (#1313)
• ✅ Multi-Agent CLI Support: Created .claude/ directory with Claude Code compatibility files (CLAUDE.md, rules, skills, commands, settings). Documented multi-agent CLI support (OpenCode + Claude Code) in docs/README.md. (#1291, #1299)

Changed

• ✅ Ollama 0.30.7: Bumped inference engine from 0.20.5 to 0.30.7. (#1314)
• ✅ Vault 2.0.2: Bumped secret management from 1.18 to 2.0.2. (#1314)
• ✅ PostgreSQL 18.4: Bumped database from 17.9 to 18.4 with updated mount path (/var/lib/postgresql per 18+ Docker image requirement). (#1314)
• ✅ Grafana 13.0.2: Bumped observability UI from 12.4.2 to 13.0.2. (#1314)
• ✅ Alertmanager v0.32.2: Bumped alerting from v0.28.0 to v0.32.2. (#1314)
• ✅ Loki 3.7.2: Bumped log aggregation from 3.3.0 to 3.7.2. (#1314)
• ✅ cAdvisor v0.55.1: Attempted bump to v0.57.0 (not available on GCR); reverted to v0.55.1. (#1314)
• ✅ AGENTS.md Consolidation: Refactored AGENTS.md from ~350 lines to ~207 lines, removing redundant content and consolidating the canonical agent operating contract. (#1300)

Fixed

• ✅ PostgreSQL 18 Mount Path: Changed volume mount from /var/lib/postgresql/data to /var/lib/postgresql to satisfy PostgreSQL 18+ Docker image layout requirements. (#1315)
• ✅ Vault Bootstrap Reliability: Fixed Vault init and stack start reliability issues, resolving race conditions between Vault initialization, bootstrap agents, and PostgreSQL startup. (#1289, #1290)
• ✅ Deprecated Profile References: Removed stale references to deprecated usr and dev profiles from docs/developer/adding-services.md. (#1298)
• ✅ Workflow Guard Skill: Corrected dead references to workflow-governance.md in .opencode/skills/workflow-guard/SKILL.md. (#1297)

Documentation

• Getting Started
• Development Workflow
• Changelog

---

Full Changelog: v1.1.24...v1.1.25

AIXCL v1.1.24

AIXCL v1.1.24

Vault bootstrap reliability, multi-agent CLI support, and agent governance consolidation.

What's New in v1.1.24

Added

• ✅ Cross-Tool CLI Compatibility: Added CLAUDE.md and .claude/ directory for Claude Code support with independent rules, skills, and commands (#1291)
• ✅ Multi-Agent CLI Documentation: Added cross-tool compatibility note to docs/README.md documenting support for both OpenCode and Claude Code (#1299)

Changed

• ✅ AGENTS.md Consolidation: Reduced from 473 lines to 207 lines (56% reduction). Detailed workflow content migrated to docs/developer/development-workflow.md. Version bumped from 1.6 to 2.0. (#1300)

Fixed

• ✅ Deprecated Profile Docs: Removed usr and dev profiles (no longer in codebase) from adding-services.md examples (#1298)
• ✅ Dead Workflow Reference: Fixed Compliance Rules table in .opencode/skills/workflow-guard/SKILL.md. Changed non-existent workflow-governance.md references to DEVELOPMENT.md (#1297)
• ✅ Vault Init Reliability: Fixed Vault initialization and stack start reliability issues on first boot and warm restart (#1289, #1290)
• ✅ Vault Anonymous Volumes: Fixed anonymous volumes from Vault agent containers and improved token refresh mechanism (#1276, #1288)
• ✅ Podman Auto-Configuration: Stack init now auto-configures Podman alias, DOCKER_HOST, and initializes volumes (#1277)
• ✅ Security Test Email: Corrected test email address to admin@example.com in CI security test (#1278)
• ✅ ShellCheck Version: Added ShellCheck version check and installation instructions with environment validation (#1281)
• ✅ Vault Engine Detection: Fixed Vault checks to use DOCKER_BIN or active engine detection instead of hardcoded docker (#1275)
• ✅ Profile Compose Pull: Fixed compose pull to only pull profile services, avoiding pulling all images (#1274)

Removed

• None in this release

Documentation

• Getting Started
• Development Workflow
• Changelog

---

Full Changelog: v1.1.23...v1.1.24

AIXCL v1.1.23

AIXCL v1.1.23

Cross-tool CLI compatibility (Claude Code support), documentation consolidation, profile fixes, and Vault/Podman improvements.

What's New in v1.1.23

Added

• ✅ Cross-Tool CLI Compatibility: Added CLAUDE.md and .claude/ directory for Claude Code support with independent rules, skills, and commands (#1291)
• ✅ Multi-Agent CLI Documentation: Added cross-tool compatibility note to docs/README.md documenting support for both OpenCode and Claude Code (#1296)

Changed

• ✅ AGENTS.md Consolidation: Reduced from 473 lines to 207 lines (56% reduction). Detailed workflow content migrated to docs/developer/development-workflow.md. Version bumped from 1.6 to 2.0. (#1293)

Fixed

• ✅ Deprecated Profile Docs: Removed usr and dev profiles (no longer in codebase) from adding-services.md examples (#1294)
• ✅ Dead Workflow Reference: Fixed Compliance Rules table in .opencode/skills/workflow-guard/SKILL.md. Changed non-existent workflow-governance.md references to DEVELOPMENT.md (#1295)
• ✅ Vault Init Reliability: Fixed Vault initialization and stack start reliability issues on first boot and warm restart (#1289)
• ✅ Vault Anonymous Volumes: Fixed anonymous volumes from Vault agent containers and improved token refresh mechanism (#1276)
• ✅ Podman Auto-Configuration: Stack init now auto-configures Podman alias, DOCKER_HOST, and initializes volumes (#1277)
• ✅ Security Test Email: Corrected test email address to admin@example.com in CI security test (#1278)
• ✅ ShellCheck Version: Added ShellCheck version check and installation instructions with environment validation (#1281)
• ✅ Vault Engine Detection: Fixed Vault checks to use DOCKER_BIN or active engine detection instead of hardcoded docker (#1275)
• ✅ Profile Compose Pull: Fixed compose pull to only pull profile services, avoiding pulling all images (#1274)

Removed

• None in this release

Documentation

• Getting Started
• Development Workflow
• Changelog

---

Full Changelog: v1.1.22...v1.1.23

AIXCL v1.1.22

AIXCL v1.1.22

Release v1.1.22 -- Vault unseal documentation and CI dependency update.

What's New in v1.1.22

Changed

• ✅ Vault Unseal Documentation: Documented Vault unseal requirement after stack restart in README.md and QUICKSTART.md. (#1248)

Fixed

• ✅ CI Release Action: Bumped softprops/action-gh-release from 2 to 3 in release workflow, upgrading action runtime from Node 20 to Node 24. (#1254)

Documentation

• Getting Started
• Development Workflow
• Changelog

---

Full Changelog: v1.1.21...v1.1.22

AIXCL v1.1.21

AIXCL v1.1.21

Release v1.1.21 -- Podman rootless compatibility, Vault credential isolation, service startup resilience, and fork workflow documentation.

What's New in v1.1.21

Added

• ✅ Fork Sync Workflow Documentation: Added upstream remote setup, branch sync, and rebase instructions to CONTRIBUTING.md for external contributors. (#1246)

Changed

• ✅ Email Defaults: Reverted all service email defaults from localhost and test domains to admin@example.com for first-start compatibility. Affects init-secrets.sh, README.md, CI workflows. (#1243)
• ✅ Localhost Refactor: Replaced aixcl.local references with localhost across docs, tests, and config for consistency. (#1245)

Fixed

• ✅ Podman Autodetect: Added set_compose_cmd() call to status() in stack.sh, mirroring start/stop/restart behavior. Fixes Docker socket errors on Podman-only systems. (#1242)
• ✅ Podman Rootless Compatibility: Added rootless directory setup, GPG_TTY handling, and token decrypt fixes for Podman environments. (#1242)
• ✅ Vault Credential Isolation: Bootstrap agents now write both password and email secrets from Vault KV to /run/secrets/, removing sensitive identity from .env. Fixes rootless restart loops. (#1242)
• ✅ Grafana/pgAdmin Startup Race: Added 60-second wait-and-retry loops for Vault bootstrap secrets, preventing fail-fast exits on fresh deployments. (#1244)
• ✅ POSIX Compliance: Replaced local keyword with underscore-prefixed variables in bootstrap-password scripts to satisfy ShellCheck SC3043. (#1242)
• ✅ Loki Documentation: Clarified in README that Loki has no web UI and Grafana should be used for log browsing.

Documentation

• Getting Started
• Development Workflow
• Changelog

---

Full Changelog: v1.1.20...v1.1.21

AIXCL v1.1.20

AIXCL v1.1.20

Release v1.1.20 -- follow-up to v1.1.19, includes the vault-status.sh hotfix.

What's New in v1.1.20

Fixed

• ✅ Vault Status Unknown State: Fixed check_vault_health() in lib/aixcl/commands/vault-status.sh to correctly parse "sealed": false from Vault health API. Same jq false handling bug as #1229, different file. Also fixed false "⚠ Vault needs initialization" warning. (#1234, #1235)

Documentation

• Getting Started
• Development Workflow
• Changelog

---

Full Changelog: v1.1.19...v1.1.20