All notable changes to this project are documented in this file.

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

• lib/validation.sh module with check_artifacts() (inspects .aidd/ project-level assertions against a per-artifact severity catalog and writes .artifacts-check.json) and suggest_post_interview_cleanup() (prompts operators to close the interview → doc2feature loop when responses exist without an assertions.md). Integrated into aidd.sh via a new --check-artifacts mode and an end-of-interview nudge.
• audits/ASSERTIONS.md — Project Assertions / Invariants Audit framework for verifying the codebase honors every invariant declared in .aidd/assertions.md.
• Audit-review bundle (2026-04-23): full /audit-review pass across every stale audit definition. Thirteen audit files touched:
  • SECURITY.md v3.2 → v3.3: added 10 checklist rows across password security, SQL injection prevention, rate limiting, transport headers, WebSocket security, and encryption; hoisted the MFA QR dangerouslySetInnerHTML exemption; narrowed rate-limit production-scope wording.
  • DEPLOYMENT.md v2.0 → v3.0: removed all Vercel/Sentry/Next.js/ winston/Codecov content; rebuilt around containerized self-host with health checks, metrics, structured logging, alerting, audit log archival, and backup verification. Now consolidates the retired MONITORING.md.
  • PERFORMANCE.md v1.0 → v2.0: Prisma → Drizzle examples; added ResponsiveContainer ban + recharts v3 <Cell> deprecation + useContainerWidth hook; React 19 concurrent features section (useTransition, useDeferredValue); manual memoization flagged unless profiling-justified.
  • LIGHTHOUSE.md v1.0 → v2.0: FID purged, INP documented with lab-measurement caveat (use TBT as proxy), crawltest integration added, pre-2026-04-05 LCP/FCP crawler measurement-artifact note.
  • DEVOPS.md v1.0 → v2.0: restructured as CI-process-only with hard scope boundary to DEPLOYMENT; SHA-pinned actions, frozen- lockfile, branch protection, dependabot, gitleaks, CODEOWNERS guidance; IaC/Terraform section removed.
  • TESTING.md v1.0 → v2.0: full rewrite around the architectural rule No Unit Test Frameworks. Every vitest/jest/RTL/cypress/ playwright mention now appears only as an anti-pattern flag; the canonical 14-step smoke:qc pipeline is encoded verbatim from STACK.md.
  • DEAD_CODE.md v1.2 → v1.3: knip + knip.json elevated to first-class; added check:feature-integration + React.lazy renamed-default adapter + dual SQLite/Postgres schema exclusion
    • CSS-only imports + orphaned Zustand stores; new Boundaries-vs- Adjacent-Audits matrix.
  • CONVEX.md v1.1 → v1.2: fixed two factual errors (fabricated convex.json environment block; process.memoryUsage() not in V8 runtime); added sections for Convex Components (stable 1.17+), Cron Jobs, HTTP Actions, Clerk+Convex auth wire-up.
  • TECHDEBT.md v1.x → v2.0: cross-audit relationships, false positives, missing stack checks. Subsequent v2.0 re-audit fixed a stale footer date and the configLoader.ts → configSecrets.ts env-exception reference; broadened the React Compiler exception clause; labeled the bash-only pre-audit commands.
  • SCHEMA_CONSTRAINTS.md v1.2 → v1.3: softened grep commands with false-positive warnings; added real-world template unique-column inventory (incl. apiKeys.keyHash intentionally non-unique due to bcrypt salting); added dual-composite uniqueness pattern (oauthAccounts); added Drizzle partial unique index syntax; clarified dual-dialect reality (apps carry both schema/ and schema-pg/).
  • SPERNAKITV1.md v2.0 → v2.1 and SPERNAKITV2.md v3.0 → v3.1: archived with lifecycle banner, retained read-only for historical reference; superseded by SPERNAKIT.md v3.4.
  • MONITORING.md: deleted. Content consolidated into DEPLOYMENT.md.

• Breaking (operators must migrate): DEFAULT_SPEC_FILE flipped from app_spec.txt to spec.md. All prompts, scripts, help messages, docs, and benchmark fixtures now reference .aidd/spec.md. Projects with an existing .aidd/app_spec.txt must rename the file (git mv .aidd/app_spec.txt .aidd/spec.md) — no backward-compat fallback. XML-formatted specs should be converted to markdown headings during the migration.
• zrun system prompt now explicitly forbids npm/npx (previously just preferred bun/bunx).
• docs/audit_guide.md updated: removed MONITORING from audit inventory tables and example command lines; updated DEPLOYMENT description to reflect its consolidated scope; updated DEVOPS description to drop IaC and focus on CI/quality gates; bumped TECHDEBT estimated time to 2-6h to match its v2.0 frontmatter.

• Corrected future-dated last_updated frontmatter on two audit definitions that would have misled the /audit-review freshness logic: TECHDEBT.md (2026-06-28 → 2026-04-23) and SCHEMA_CONSTRAINTS.md (2026-07-11 → 2026-03-30). Also corrected a matching future-dated audit report in aidd-web (SCHEMA_CONSTRAINTS-2026-05-18.md → -2026-04-23.md).

• Benchmark harness now understands zrun providers. tools/run-benchmark.mjs forwards stack.provider as ZRUN_PROVIDER on spawn so a zrun-ollama stack and a zrun-zhipu stack can coexist on the leaderboard instead of collapsing into one row. buildRunMatrix also honours per-task scoredRepetitions / warmupRepetitions overrides so a diagnostic task can run at a different cadence from the 1+3 standard.
• New quiz task + benchmarks/fixtures/quiz/ fixture: a codebase comprehension diagnostic that asks the agent to read bundled snapshots of zrun/src/tools/index.ts, zrun/src/config.ts, and benchmarks/manifest.json and answer four identifier-lookup questions. Scored by regex hit-rate per question with an ANSI-stripping iteration-log fallback for models that emit answers to stdout instead of calling write_file.
• Four new Ollama stacks in benchmarks/manifest.json covering the models the quiz was run against: zrun-ollama-llama32-native, zrun-ollama-qwen35-9b-native, zrun-ollama-gpt-oss-20b-native, and zrun-ollama-qwen25-cline-native. Existing zrun-glm51-native gains an explicit provider: "zhipu" for schema consistency.
• tools/quiz-rank.mjs renders the quiz rows from leaderboard.json as a ranked markdown table with per-question hit breakdown pulled from runs.jsonl notes.

• Ollama provider default model changed from llama3.1:8b to gpt-oss:20b. In the 2026-04-19 codebase comprehension quiz, gpt-oss:20b was the only installed local model to score a clean sweep; llama3.2:latest, qwen3.5:9b, and qwen2.5-7b-cline all failed at the tool-call or response-writing layer. Users who want the older default can pin it via providers.ollama.model in zrun/config.json or pass --model llama3.1:8b per run. zrun/config.json.example and docs/ollama-integration.md updated to match.

• zrun/config.ollama.example.json. The combined zrun/config.json.example covers every shape this file did — an Ollama-only setup is just config.json.example with defaultProvider flipped to "ollama" and/or the zhipu block removed. Reduces maintenance surface and the chance of the two examples drifting out of sync on future changes.

• ZRun config.json gains a multi-provider shape: both Zhipu AI and Ollama settings can live in the same file under providers.zhipu and providers.ollama, alongside an optional defaultProvider field. No more hand-editing JSON to swap backends.
• Runtime provider selection via four cascading signals (highest first): the --provider <name> CLI flag, the ZRUN_PROVIDER env var, auto-inference from --model <name> when the model is uniquely owned by one provider's registry (e.g. --model llama3.1:8b routes to ollama, --model glm-5.1 routes to zhipu), and defaultProvider in the config.
• Ollama provider registry now carries a curated list of known model families (llama3.1, qwen2.5, codellama, deepseek-coder-v2, gpt-oss, etc.) used for --model X → provider inference. The actual installed model list is still discovered at runtime from /api/tags.
• Startup banner now shows both provider and model (e.g. [zrun] Provider: ollama Model: llama3.1:8b) so it's always obvious which backend fired for a given run.

• ZRunFileConfig (on-disk) is now distinct from ZRunConfig (resolved). The normalizer promotes a legacy flat config ({ apiKey, model, baseUrl } at top level) into providers.zhipu automatically, so existing setups continue to work without any migration.
• API-key-missing error now names the right config path (providers.zhipu.apiKey) instead of the deprecated flat apiKey.
• zrun/config.json.example rewritten to the multi-provider shape with both zhipu and ollama entries populated as a starting point.
• Root package.json and VERSION aligned at 0.14.0; zrun/package.json bumped 0.3.0 → 0.4.0.

• ZRun gains a provider abstraction layer. ZRunConfig now carries a provider field (defaults to "zhipu" so existing configs keep working unchanged) and both apiKey and baseUrl are optional — each provider declares its own defaults via src/providers/index.ts.
• Ollama support via provider: "ollama". Uses Ollama's OpenAI-compatible endpoint, health-probes /api/tags with a 5s timeout on both the probe and the model listing so a hung local instance can no longer stall CLI startup. When model is unspecified, auto-selection prefers the provider's declared defaultModel if installed, else sorts alphabetically so repeat runs are deterministic.
• zrun/test-ollama.ts — a read-only /api/tags probe that reports installed models and exits non-zero when the server is unreachable or has no models pulled.
• docs/ollama-integration.md — end-to-end Ollama setup, model recommendations, troubleshooting, migration from Zhipu AI, and security notes.
• .aidd/features/ records for zrun-provider-abstraction, zrun-ollama-integration, and zrun-ollama-docs-testing.

• src/config.ts loadConfig is now async to accommodate the Ollama health probe. The only call site is src/index.ts, which awaits it at startup.
• src/client.ts no longer reuses the provider name as a dummy API key; providers that don't require auth (Ollama) get a named NO_AUTH_DUMMY_KEY sentinel so the OpenAI SDK constructor accepts a non-empty value.
• Root package.json version aligned to VERSION (0.11.2 → 0.13.0); the two had drifted during the 0.12.0 release.

• Zhipu default baseUrl in src/config.ts was missing the /api/ path prefix (https://api.z.ai/coding/paas/v4 → https://api.z.ai/api/coding/paas/v4). config.json.example already had the correct URL, so users who copied the example were unaffected; only users relying on the in-code default would have hit a 404 at first request.

• Coordinator mode (--coordinator) for fleet-level analysis. A coordinator agent reads a fleet summary JSON, evaluates every project across all signal dimensions, identifies cross-project patterns, and produces structured suggestions for the aidd-web approval queue. Requires --fleet-summary and --coordinator-output paths; optional --suggestion-schema for output schema reference. Forces single-iteration execution.
• Coordinator prompt template (prompts/coordinator.md) with task type selection matrix, risk-level heuristics, cross-project pattern detection, and structured JSON output schema.

• Feature IDs now use clean descriptive slugs (e.g., user-authentication, dashboard-page) instead of the feature-{timestamp}-{random} format. Remediations and audit findings retain their existing prefixed formats. Updated validation regex, prompts, documentation, and the generate-features.sh tool to match.
• Updated prettier from 3.8.2 to 3.8.3.

• Codex CLI rate limit detection now works correctly. Previously, rate limits from Codex ("You've hit your usage limit") were missed due to an unbound PATTERN_RATE_LIMIT variable in the bash -c subprocess and a pattern mismatch ("hit your limit" vs "hit your usage limit"). Iterations fell through as generic exit=1 failures instead of sleeping until the rate limit reset.
• Widened PATTERN_RATE_LIMIT from "hit your limit" to "hit your" to match both Claude Code/ZRun and Codex rate limit message formats.
• Added [RATE_LIMITED] tag detection to monitor_coprocess_output as a secondary detection path for JSON-parsed CLIs.
• Extended parse_rate_limit_reset regex to handle Codex's "try again at 5:19 AM" format and uppercase AM/PM.
• Fixed latent unbound variable in Claude Code's json-parser.sh (same root cause, currently unreachable but would surface if stream-json format changed).

• Benchmark harness with fixture manifests, disposable workspaces, cohort comparisons, and machine-readable result artifacts.
• Benchmark documentation covering fixtures, outputs, and report generation.
• New benchmark package scripts for full runs, dry runs, and report-only rebuilds.
• Interview mode (--interview [FILE]) for iterative codebase Q&A. Processes one question per iteration from .aidd/questions.md (or a supplied file), auto-detecting ## heading or ?-terminated line formats. Writes per-question responses to .aidd/responses/responseN.md and maintains a responses.md index of status and links. The interview prompt is read-only — the agent is forbidden from modifying code, features, changelogs, or other metadata, and git-based stuck detection is skipped because only responses/ is expected to change. Progress is tracked by response-file count, so partial runs resume at the next unanswered question and the loop exits cleanly once every question has a matching response file.

• Codex CLI execution now uses the bash-oriented bypass path to avoid Windows sandbox shell mismatches during unattended runs.
• Feature validation now requires a dependencies array, with [] as the canonical empty value.
• ZRun defaults now allow longer sessions by raising maxTurns to 500.

• Prompting and audit guidance now enforce a stronger verification gate before audit findings are converted into remediation work.

• Codex CLI backend with codex exec --json support and JSONL parsing.
• CLI-specific prompt prelude loading from prompts/_cli/*.
• React Composition Patterns and refreshed React Best Practices audits.

• Idle nudge timeout increased to reduce premature interruptions.