Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Spec version (separate cadence from binary): see SPEC.md Changelog §19. The spec and the binary version independently — the binary tracks SemVer over the implemented surface; the spec tracks decisions and architecture.

[1.3.0] — 2026-05-28

Added

• ai clone identity routing: reads ~/.config/aiConstitution/metadata/projects.json and applies git config user.name/email per URL-pattern match; --identity <name> forces a named entry (#394)
• ai hooks available: lists hooks from both the embedded library and the ai-hook atom registry on skill-atoms.com (#397, #399)
• ai hooks list: per-client wiring columns — INSTALLED / CLAUDE (global|project|-) / COPILOT (#400)
• ai hooks install --copilot: wires Constitution.runtime.md into ~/.copilot/instructions/ (#400)
• ai hooks propose: scaffolds .py or .sh hook files from a description or --from-violation audit log (#389)
• ai audit override / ai audit violation: write structured markdown records to ~/.ai/audit/ (#386)
• ai memory retire: archives a named memory entry and removes it from MEMORY.md (#386)
• ai issue file: creates GitHub issues from description, body, or --from-audit log files (#387)
• ai hooks share, ai mode share, ai persona share, ai profile share, ai skills share: file upstream contribution issues on the atom registries (#387)
• ai skills available: deduplication hides sub-skills listed in depends_on; shows parent with (+N) count (#375, #379)
• ai skills install: resolves depends_on and installs all sub-skills automatically (#375)
• ai skills link: symlinks installed skills into ~/.claude/skills/ and ~/.copilot/instructions/ (#373)
• ai setup: skill selection step after wizard; idempotent ~/.claude/CLAUDE.md rewrite (#368, #370, #376)
• ai doctor: hook wiring completeness check; checkPersonasBlock only warns when persona sections exist (#391, #404)
• ai status: unified vs 4-file constitution detection; correct wired hook count (#390, #402)
• skill-atoms: type: "ai-hook" added to schema; 13 governance hooks published as atoms (#55 in skill-atoms)

Fixed

• ai update --migrate now calls the real migration pipeline (runMigrateFlatten, runMigrateAddBehavioral, runMigrateGenerateRuntime) instead of printing placeholder text (#396)
• ai hooks install --all: hook wiring now covers all 11 event hooks, not just 5; readWiredHookNames handles both group and flat settings.json formats (#401)
• ai setup: no longer produces misleading migration warning on fresh TTY install; creates audit/, memory/, governance/ directories on first run (#361, #368)
• ai doctor and ai status no longer false-positive on missing Common.md/Code.md/Writing.md for unified-model installs (#390)
• ai hooks list: __init__.py, _lib.py, test_*.py, *.example, *.toml filtered from display (#381, #400)

Changed

• ai atoms group removed; atom management delegated to the atoms binary from convergent-systems/atoms (#363)
• ai brand, ai sync status, ai plan list/new/show implemented (#354, #355)
• ai skills available + ai hooks available: now fetch from https://ai-atoms.com/exports/catalog.json — single CDN fetch replaces GitHub API calls (#416)
• ai skills install: fetches skill content from ai-atoms.com catalog (system_prompt_fragment field) instead of GitHub API (#418)
• ai hooks install: fetches hook scripts from ai-atoms.com catalog (script field) with embed fallback for infrastructure files; 13 hooks shipped by catalog (#419)
• ai hooks run <slug>: new portable cross-platform hook runner — settings.json entries now use ai hooks run audit instead of absolute python3 paths (#411)
• ai constitution setup: new subcommand bootstrapping a personal constitution via the guided TUI wizard (#408)
• ai constitution restore --url <git-url>: restore ~/.ai/ from a personal git repo URL (#408)
• ai setup TUI: hook selection step added before skill selection; users pick individual hooks interactively (#410)
• ai-atoms.com: 14 governance hook atoms published (13 with Python scripts + hook/lib); hook-v1.json schema extended with script and depends_on fields
• 281 skills in ai-atoms.com catalog: 18 additional convergent-systems skills (commit, cleanup, diagram, make-clean, make-work, refactor, etc.) published to ai-atoms.com (previously only in skill-atoms.com)
• Website: ai-constitution.convergent-systems.co updated — four-file model replaced with unified Constitution.md description; version updated to v1.3.0 (#426)

Changed (post-initial entry)

• Embed stripped: 12 hook .py scripts removed from binary embed; hooks now source exclusively from ai-atoms.com catalog with _lib.py remaining as the only embedded infrastructure (#424)
• ai skills install fallback: when a skill isn’t in ai-atoms.com catalog yet, falls back to skill-atoms GitHub API automatically (#429)

Fixed (post-initial entry)

• ai hooks install --claude: purges old absolute-path entries before re-wiring so hooks don’t fire twice after upgrading (#413)
• readWiredHookNames: recognizes portable ai hooks run <slug> format alongside old python3 /abs/path format (#414)
• ai hooks list: lib.py filtered (transition artifact); audit-logger.py wired to PreToolUse (#421)
• ai status: wired hook count now reflects both group and flat settings.json formats (#402)

[1.4.3] — 2026-05-29

Added

• ai doctor compact constitution checks — detects when Constitution.compact.md is missing or when CLAUDE.md still references the full form; ai doctor --fix generates the compact form and updates the include (#460).
• ai setup reads Q36 to wire only selected clients — Claude Code and Copilot wired globally; Cursor and Codex print per-repo instructions (#459).
• All clients use compact form — Cursor (init-integrate --cursor) and Codex (AGENTS.md) now link to Constitution.compact.md (#459).

[1.4.2] — 2026-05-29

Fixed

• ai setup now wires the compact form into clients — Constitution.compact.md (~8KB) is generated immediately after Constitution.md and wired into ~/.claude/CLAUDE.md and Copilot instead of the full 38KB constitution. Both clients receive the same compressed, §ID-prefixed form on every session (#458).

[1.4.1] — 2026-05-29

Added

• ai skills available — two-line display with full untruncated descriptions; header shows count and install hints (#456).
• ai skills available -p — Bubble Tea checkbox TUI: > [x] style selection, scrolling viewport, space to toggle, a to toggle all, ctrl+d/u to page, enter to install (#457).

Changed

• ai setup skill step now uses the same checkbox TUI instead of the old numbered text prompt, and fetches from the ai-atoms catalog (single fetch) instead of per-atom GitHub API calls (#457).

[1.4.0] — 2026-05-29

Added

• ai wrap <tool> [-- args...] — cross-platform Go dispatcher for command-wrapper interception. All wrapper logic moved from bash to Go; per-OS shims (git.cmd, git.ps1, gh.cmd, gh.ps1) delegate to it. Closes the Windows enforcement gap where protected-branch and pre-commit-secret gates silently did not fire (#443).
• ai doctor: Windows Python App Execution Alias detection + --fix — detects zero-byte Store stubs that shadow a real Python installation; --fix removes them automatically (#451).
• ai doctor: blocking wrapper hook drift check — verifies every blocking pre-hook in command-wrappers.toml is installed on disk; surfaces [⚠] with remediation hint (#447).
• Per-pattern severity in patterns.json — block_level: "blocking" (default, abort) or "warn" (emit warning, allow). High-confidence patterns (GitHub, AWS, GCP) are explicitly "blocking"; medium-confidence patterns with false-positive risk are "warn" (#455).
• Local allowlist in patterns.local.json — disable: ["jwt-token"] suppresses specific patterns per-repo without touching the global canonical file (#455).
• make docs — generates the README command table from NewRootCmd().Commands() so it can’t drift; gen_docs.go is the generator (#454).
• ParseSectionsAny in constitution.go — handles both legacy ## N. Name Rules and template-generated ## §N Name section headers; enables ai compress --check-coverage on normally-generated constitutions (#448).
• ai compress --check-coverage — compares full-extraction rule IDs against Constitution.compact.md; exits non-zero on missing IDs (#446).
• Lossless compact form — Constitution.compact.md now generated from the rule extractor rather than a hand-written string; 158 rule IDs verified end-to-end (#448, #449).
• Go BlockLevel + IsBlocking() helpers in src/pkg/patterns/patterns.go — propagates block_level from patterns.json into Match values (#455).

Changed

• ai setup does a full minimum install — now runs installAllHooksAndWire (catalog + infrastructure + settings.json wiring), embed.ExtractWrappers (platform-appropriate command-wrappers), and Windows Python prerequisite fix before writing hooks (#452).
• Hook enforcement is now fail-closed — runHookForWrap returns exit 1 + ENFORCEMENT DEGRADED message when a blocking hook file is missing or Python is absent, instead of silently returning 0 (#445).
• Config error in ai wrap fails closed — unreadable command-wrappers.toml exits 1 with a remediation hint instead of passing through to the real binary (#445).
• ai wrap does not forward tool args to hooks — hooks read git state via git diff --staged / git branch --show-current; passing git subcommand tokens caused argparse failures in strict-mode hooks (#453).
• Hook stdin is nil in wrapper mode — prevents pre-hooks from consuming stdin the real binary needs (A.3) (#453).
• worktree-guard is advisory — marked enforcement = "advisory" in command-wrappers.toml; convention enforcement, not a security gate (#445).
• Constitution template is cross-platform — §3.4.1 presence test now includes per-OS table (POSIX sh / PowerShell / cmd); §3.4.2 clipboard rule has per-OS commands; 0600/0400 replaced with portable intent; ls -la replaced with platform-neutral description; path-separator normalization clause (§3.2.13); portable path resolution (§3.5.6); shell-neutral command discipline (U18); line-endings/encoding (U19) (#450).
• ruleHeadRe and bulletSubRuleRe updated to capture three-level IDs (N.M.K) in addition to two-level (#448).
• Template bold subsection heads stripped of § prefix (**§N.M.K.** → **N.M.K.**) so the numeric ID is extractable (#448).
• ExtractWrappers is platform-filtered — .cmd/.ps1 only on Windows; bash shims only on POSIX; notify-me variants on all platforms (#443).
• SPEC.md label standardized to v1.0.0-draft everywhere (#447).
• README command table regenerated from NewRootCmd().Commands() — alphabetical, source-of-truth, adds ai wrap (#454).

Fixed

• Duplicate newCompressCmd() registration in root.AddCommand removed (#441).
• Go version floor standardized to 1.26 across all modules and .tool-versions (#441).
• renderCompactConstitution hand-written body replaced with extractor-based generator (#449).
• §4.1–§4.8 and §3.2.2/§1.6 plain bullets tagged with stable N.M.K IDs in constitution template (#449).
• TestDoctorTerminalNotifierFound assertion tightened to per-line check (was false-positive when any [⚠] appeared alongside any terminal-notifier mention) (#447).
• command-wrappers.toml header updated to reflect post-fail-closed enforcement model (#447).

[1.4.3] — 2026-05-29

Added

• ai setup installs Claude official plugins — when Claude Code is selected in Q36, setup registers anthropics/claude-plugins-official marketplace and installs security-guidance (always) plus any plugins selected in Q36c (superpowers, amendment-author, hook-author, etc.) (#462).
• ai doctor compact constitution checks — detects when Constitution.compact.md is missing or when CLAUDE.md still references the full form; ai doctor --fix generates the compact form and updates the include (#460).
• ai setup reads Q36 to wire only selected clients — Claude Code and Copilot wired globally; Cursor and Codex print per-repo instructions (#459).
• All clients use compact form — Cursor and Codex AGENTS.md now link to Constitution.compact.md (#459).

Fixed

• Skill symlinks for make-work, make-review, make were pointing to macOS temp dirs left by test runs; relinked to correct ~/.ai/skills/ targets (#461).
• Skills install tests now isolate CLAUDE_SKILLS_DIR to prevent writing dangling symlinks into the real ~/.claude/skills/ (#461).
• env and .env* added to .gitignore to prevent accidental commit of local credentials.

[1.4.4] — 2026-05-29

Added

• ai setup installs Claude official plugins — registers anthropics/claude-plugins-official marketplace and installs security-guidance (always) plus Q36c selections (#462).
• ai setup wires clients from Q36 selection — only selected clients wired; Cursor/Codex print per-repo reminder (#459).
• ai doctor compact checks — detects missing Constitution.compact.md or stale CLAUDE.md include; --fix corrects both (#460).
• Profile picker wired — Q07 answer now maps to correct domain sections in Constitution.md (code → Technical, writing → Prose) (#469).

Fixed

• Six os.Symlink() calls replaced with symlinkOrCopy() — falls back to file copy on Windows without Developer Mode (#464, #470).
• Hook validation uses discoverPythonArgs() instead of hardcoded python3; bash validation skipped on Windows (#465, #470).
• Pre-commit hook body uses portable ai hooks run instead of exec python3 with bash shebang (#465, #470).
• Path separator checks now match both / and \ for Windows AI_ROOT paths (#466, #470).
• checkBinPath skips POSIX system bin list on Windows (#467, #470).
• Stale Code.md not found line removed from ai version output — it is a section in Constitution.md (#463).
• Skill symlinks make-work, make-review, make relinked from broken temp paths; tests now isolate CLAUDE_SKILLS_DIR (#461).

[Unreleased]

Spec — v0.10: GitHub Actions trinity

• workflow-atoms.com (introduced v0.9) splits into three sibling registries (action-atoms.com, workflow-atoms.com, pipeline-atoms.com) matching how GitHub layers actions / workflows / pipelines. Seven atom registries total; eight Convergent Systems Astro sites (SPEC §14.1).
• Canonical-identity vs consumption-form (SPEC §7.11.1): atoms.com URLs are the canonical identity humans/CLI/docs use; GHA’s uses: accepts only owner/repo@ref; the CLI translates atoms.com URLs to the GH-grammar form at file-write time. Each atom version corresponds to exactly one git tag on the backing repo; ai doctor surfaces drift.
• New CLI verbs: ai action and ai pipeline (same shape as ai workflow). All three accept the canonical atoms.com URL form as the install argument.
• Wizard adds Q36d/e/f/g in Phase 8 (one per layer plus the install-mode prompt).
• settings.toml v0.4: adds actionRegistry, pipelineRegistry, [action], [pipeline], [atoms.cache.action], [atoms.cache.pipeline]; the v0.9 [workflow] install moves to [atoms] install (cross-layer setting).
• The v0.9 atom-action data-fetcher idea is dropped — it conflated runtime data-atom fetching (still useful, but a separate concern) with workflow-atom consumption (which can’t be runtime-fetched because GHA parses YAML at workflow-init time).

Changed — refactor: single-binary distribution

• Hook library is now embedded into the ai binary via //go:embed (see src/cmd/ai/embed/). Repo-root hooks/ and bin/ directories removed. The 15 hook files + wrapper templates + patterns.json
  • command-wrappers.toml live at src/cmd/ai/embed/{hooks,wrappers}/. Extracted onto disk at install time via ai setup or ai hooks install --all / ai hooks install command-wrappers.
• ai clone <url> subcommand replaces bin/clone shell script. Identity-routing against metadata/projects.json is stubbed for v0.8; the v0.8 implementation runs git clone and installs the pre-commit secret hook into the clone.
• ai audit rotate subcommand replaces bin/audit-rotate.sh. Same behavior (gzip prior-month JSONLs); --dry-run flag honored.
• ai hooks install is now the canonical surface for materializing the embedded library: --all, <name>, or command-wrappers. Idempotent; --force to overwrite.
• bin/ai PATH-shim removed. A misconfigured PATH already yields a clear “command not found”; the stub provided no signal beyond that.
• .goreleaser.yaml ldflags fixed. Previously targeted main.version (no such var); now stamps .../internal/buildinfo.{version,commit,date} correctly. ai version output: v0.8.0 (commit abc1234, built 2026-05-23T08:00:00Z).

Added

• SPEC.md v0.8 — authoritative implementation specification.
• questions.yaml v0.8 — wizard question taxonomy.
• settings.toml.example — canonical defaults for ~/.config/aiConstitution/settings.toml.
• GOALS.md — G1-G7 goals, non-goals, anti-goals.
• ARCHITECTURE.md — navigational architecture overview, indexed to SPEC.md sections.
• docs/adr/ — ADR-0001 through ADR-0004 backfilled from spec decisions:
  • ADR-0001 Atoms architecture (versioned immutable units).
  • ADR-0002 Command Wrapper Facade for cross-tool enforcement.
  • ADR-0003 No trufflehog; patterns.json + optional gitleaks.
  • ADR-0004 Markdown issue templates in v0.8; YAML Issue Forms deferred.
• .github/ISSUE_TEMPLATE/ — six Markdown templates per SPEC.md §9.5 and §14.3: epic, feature, story, task, hook, finding.
• hooks/ — Python stdlib-only hook library: patterns.json, audit.py, secret-block.py, secret-precommit.py, branch-guard.py, worktree-guard.py, no-verify-strip.py, destructive-gh-guard.py, destructive-terraform-guard.py, destructive-kubectl-guard.py, audit-command.py, checkpoint-tick.py, command-wrappers.toml.
• bin/ — helper scripts: clone, audit-rotate.sh, git.template, gh.template, ai (PATH-shim error stub).
• governance/policy/branch-guard.json — canonical protected branch set.
• governance/wizard/ — pointer to questions.yaml.
• governance/seed/answers.example.yaml — wizard answer template.
• src/cmd/ai/ — cobra-based CLI scaffold; every verb from SPEC.md §3 is registered (stubs for v0.8).
• src/internal/ — packages: config, paths, audit, state, hooks, atoms (all skeletal).
• src/pkg/patterns/ — Go bindings for patterns.json (consumes the same canonical pattern set as the Python hooks).
• src/pkg/version/ — build-time version stamping (-ldflags "-X .../version.Version=…").
• web/ai-constitution/ — Astro scaffold for the methodology site. No live brand-atoms fetch (deferred); inline brand tokens from [email protected] per SPEC.md §14.4.

Changed

• .github/workflows/secret-scan.yml — replaced trufflehog with a diff scan against hooks/patterns.json. SPEC.md §10.4 forbids trufflehog; the canonical CI net is gitleaks (opt-in) and the patterns.json set is authoritative for what gets blocked.

Spec corrections (v0.8 → see SPEC.md §19)

• Fixed typo: itsx own → its own (header status line).
• Fixed section numbering: §13.1–13.4 (Settings.toml Schema) and §14.1–14.4 (Brand Integration) had subsections labeled with the previous section’s number; now consistent with their parent.