v0.4.5 — install.sh --ref flag

Adds --ref flag (and EDIKT_REF env var) to install.sh so users can pin to a specific tag without editing the script.

Install (default — v0.4.5)

```bash
curl -fsSL https://raw.githubusercontent.com/diktahq/edikt/v0.4.5/install.sh | bash
```

Install a specific older tag

```bash
curl -fsSL https://raw.githubusercontent.com/diktahq/edikt/v0.4.5/install.sh | bash -s -- --ref v0.4.3
```

Or via env var:

```bash
EDIKT_REF=v0.4.3 curl -fsSL https://raw.githubusercontent.com/diktahq/edikt/v0.4.5/install.sh | bash
```

The ref must match `v..` (with optional prerelease suffix). Invalid refs exit with code 2 and a clear error. Leading `v` is added if missing.

What changed vs v0.4.4

• `install.sh`: added `--ref` / `--ref=` flag parsing and `EDIKT_REF` env var fallback; tag validated against a strict regex before URL interpolation
• `install.sh`: default `BRANCH` bumped from v0.4.4 to v0.4.5 (self-pinned)
• `commands/upgrade.md`: self-references bumped to v0.4.5
• `VERSION`: 0.4.4 → 0.4.5

Note on v0.5.x and v0.6.0

v0.5.0 and v0.5.1 remain retracted (marked prerelease). v0.6.0 is in active development and will support the v0.4.x → v0.6 upgrade path.

v0.4.4 — install pin (v0.5.x retraction backport)

Patch backport of v0.4.3 with one purpose: give new users a working install path while v0.5.x is retracted and v0.6.0 is in development.

What changed vs v0.4.3

• `install.sh`: `BRANCH="main"` → `BRANCH="v0.4.4"` so the bootstrap fetches the payload from an immutable tag instead of tracking main.
• `commands/upgrade.md`: `main/install.sh` and `main/VERSION` URLs swapped to v0.4.4 so `/edikt:upgrade` won't direct users back to a retracted v0.5.x install.
• `VERSION`: `0.4.3` → `0.4.4`.

Why

v0.5.0 and v0.5.1 had upgrade issues and have been marked as GitHub prereleases. v0.6.0 is in active development and will support the v0.4.x → v0.6 cross-major upgrade directly.

Install

```bash
curl -fsSL https://raw.githubusercontent.com/diktahq/edikt/v0.4.4/install.sh | bash
```

v0.5.x users

If you already installed v0.5.0 or v0.5.1, your install still works; this release does not affect you. Wait for v0.6.0 to ship for the supported upgrade path.

v0.4.3 — Phase-end evaluator, upgrade safety, evaluator hardening

Bug fixes

• Phase-end evaluator now actually runs. Previously required Claude to voluntarily follow plan.md instructions to invoke it — which never happened in the common "create plan, ask Claude to implement" flow. New phase-end-detector.sh Stop hook detects completion signals in Claude's output and auto-invokes the headless evaluator with the phase's acceptance criteria.
• Upgrade no longer silently overwrites user customizations. Classifies agent diffs into three buckets: PURE EXPANSION (auto-applied), PATH SUBSTITUTION (flagged), USER DIVERGENCE (prompts individually with diff preview and keep-mine option).
• Evaluator no longer silently degrades to read-only PASS. Subagent evaluator could inherit a sandboxed permission set without Bash, fall back to read-only inspection, and return PASS on criteria that required test execution. Captured in ADR-010.

Features

• BLOCKED verdict (ADR-010). Valid per-criterion and overall verdict. "If a criterion requires execution and execution is unavailable, verdict is BLOCKED — never PASS."
• Visible evaluator fallback (ADR-010). /edikt:sdlc:plan attempts headless first, falls back to subagent with a visible banner, and emits a failure banner when both fail. No silent degradation.
• Doctor evaluator probe (ADR-010). /edikt:doctor verifies the claude CLI is on PATH, runs a headless sanity call, and checks both evaluator templates exist.
• --eval-only {phase} flag on /edikt:sdlc:plan (ADR-010). Re-run evaluation on a specific phase without re-running the generator.

Tests

• 17 tests for phase-end-detector (pattern detection, config respect, event logging, loop prevention, no false positives)
• 16 tests for upgrade divergence classification
• Evaluator flow tests extended for BLOCKED verdict and visible fallback

---

Install: `curl -fsSL https://raw.githubusercontent.com/diktahq/edikt/main/install.sh | bash`
Docs: edikt.dev

v0.4.2 — Bug fixes: preprocessing, plan pre-flight, audit, review

Bug fixes

• Spec preprocessing. Blank line between frontmatter and preprocessing block caused shell corruption. Added missing argument-hint.
• Plan pre-flight skipped. Pre-flight specialist review and criteria validation were ordered after the conclusion message. Claude stopped at "Next: execute Phase 1" and never ran pre-flight. Reordered so pre-flight runs before writing the plan file.
• Audit inline mode. --no-edikt jump target pointed to step 6 (agent-spawning) instead of step 11 (inline audit mode).
• Gov review premature conclusion. "Next: Run /edikt:gov:compile" appeared before staleness detection finished. Moved to actual conclusion.

Tests

• 15 preprocessing format regression tests
• 5 step ordering regression tests
• 24 evaluator flow tests (pre-flight + phase-end + bypass protection)
• Version check no longer hardcoded to specific version

---

Install: curl -fsSL https://edikt.dev/install.sh | bash
Docs: edikt.dev

v0.4.1 — Upgrade agent detection, bug fixes

Bug fixes

• Upgrade: new agent detection. /edikt:upgrade now detects agent templates added in newer versions. Core agents (evaluator, evaluator-headless) are installed automatically. Optional agents are offered to the user — declined agents are added to agents.custom so future upgrades skip them.
• Upgrade: config migration. paths.soul renamed to paths.project-context. Upgrade auto-migrates existing configs.
• Subagent-stop override check. Now matches agent + finding on the same line (was two independent greps that could cross-match).
• WEAK PASS exit code. Corrected to 0 (non-blocking), was incorrectly 1.
• .gitignore negation. Fixed patterns for experiment run.sh files.
• Agent count. Corrected to 18 across website docs.
• SPEC-003. Removed BSD-only stat command.

Documentation

• Updated project-context.md for v0.4.0: hook count (9→13), quality gates, plan harness features.

---

Install: curl -fsSL https://edikt.dev/install.sh | bash
Docs: edikt.dev

v0.4.0 — Plan harness, evaluator, enforcement

Plan Harness: Iteration Tracking, Context Handoff, Criteria Sidecar

• Iteration tracking: progress table with Attempt column, 6 statuses, escalation at 3 consecutive failures, stuck at max attempts
• Context handoff: each phase has a Context Needed field, PostCompact re-injects after compaction
• Criteria sidecar: PLAN-{slug}-criteria.yaml with per-criterion status tracking

Evaluator: Headless Execution and Configuration

• Headless mode: evaluator runs via claude -p --bare with no shared context from the generator
• Evaluator config: 5 keys — preflight, phase-end, mode, max-attempts, model
• LLM evaluator in experiments: --llm-eval flag, three verdicts (PASS, WEAK PASS, FAIL)

Enforcement: Quality Gate UX and Artifact Lifecycle

• Gate override logging: overrides to ~/.edikt/events.jsonl with git identity
• Artifact lifecycle: draft → accepted → in-progress → implemented → superseded
• Plan draft warning and drift status filter

Breaking changes

• Config key paths.soul renamed to paths.project-context. Upgrade auto-migrates.

Bug fixes (from CodeRabbit review)

• subagent-stop.sh: override check now matches agent + finding on same line
• .gitignore: negation patterns fixed for experiment run.sh files
• WEAK PASS exit code corrected to 0 (non-blocking)
• Removed BSD-only stat command from SPEC-003
• Agent count corrected to 18 across website docs

---

Install: curl -fsSL https://edikt.dev/install.sh | bash
Docs: edikt.dev

v0.3.1

Bug fixes

• Init: guidelines path, VERSION stamp, PRINCIPAL prefix, review output
• SubagentStop hook: seniority prefix (Principal, Senior, Staff) broke agent slug lookup and gate matching
• Missing page: /edikt:guideline:compile website page (was dead link)
• Test fixes: all 25 suites pass after v0.3.0 regressions

Artifact generation: JSONB support and domain class diagram

/edikt:sdlc:artifacts now handles projects using JSONB aggregate storage (common DDD pattern in PostgreSQL) and generates a domain class diagram alongside the data model.

• Storage strategy detection — scans spec and migrations for JSONB signals, switches to jsonb-aggregate rendering mode
• Three entity modes in data-model.mmd — physical table (normal), JSONB-embedded (relationship label contains jsonb), reference-only (external bounded contexts, label contains ref)
• Domain class diagram (model.mmd) — new artifact, always generated alongside data-model. Mermaid classDiagram with aggregate roots, value objects, inheritance, composition

Configurable artifact spec versions

Defaults updated to latest stable. Teams can pin older versions in .edikt/config.yaml:

Format	Previous	Now (default)
OpenAPI	3.0.0	3.1.0
AsyncAPI	2.6.0	3.0.0
JSON Schema	draft-07	2020-12

artifacts:
  versions:
    openapi: "3.0.0"       # pin for tooling compatibility
    asyncapi: "2.6.0"      # pin if not ready for 3.0 breaking changes

AsyncAPI template updated to 3.0 structure (separate channels and operations blocks).

Upgrade

curl -fsSL https://raw.githubusercontent.com/diktahq/edikt/main/install.sh | bash

edikt v0.3.0

Project Adaptation, Invariant Records, and Compile Improvements

Project Adaptation (ADR-008, ADR-009)

• Three-list directive schema: directives:, manual_directives:, suppressed_directives: with SHA-256 hash-based caching
• Invariant Records: formalized governance artifact for hard constraints — committed template with Statement/Rationale/Enforcement sections
• Template lookup chain, init style detection, flexible prose input, doctor + upgrade integration

Compile Improvements

• "No exceptions." reinforcement on invariant directives with absolute language
• Reminders sentinel — pre-action interrupts in governance.md
• Verification checklist — self-audit items Claude checks before finishing
• Per-directive LLM compliance scoring in review commands
• New /edikt:gov:score command — aggregate governance quality report
• Pre-flight criteria validation — evaluator checks acceptance criteria before generator starts

Experiments

8 pre-registered experiments validating governance effectiveness:

• Governance prevents architecture and tenant violations on greenfield builds
• Governance stabilizes output under long-context pressure
• Directive format matters: MUST/NEVER + literal code tokens outperforms prose

Website

6 new governance pages, compile page rewritten, all stale command names updated, README simplified.

Full changelog

See CHANGELOG.md for the complete list.

Install / Upgrade

curl -fsSL https://raw.githubusercontent.com/diktahq/edikt/main/install.sh | bash

Then in any project: /edikt:upgrade

v0.2.3

Compile schema version (ADR-007)

/edikt:gov:compile now stamps generated governance files with a compile schema version — a small integer independent of edikt's marketing version — instead of the edikt version at compile time.

Problem this fixes: before v0.2.3, .claude/rules/governance.md was stamped with version: "<edikt-version>", conflating two unrelated cadences. Every edikt point release (even pure bug fixes) implied governance was stale and needed regeneration, but the compile output format hadn't actually changed. In the dogfood repo, we kept hand-editing governance.md's version via sed on each release to keep a test green — the file ended up lying about its own provenance (version said v0.2.2 but the compile timestamp was frozen at March 25).

New format (see ADR-007):

---
paths: "**/*"
compile_schema_version: 2
---
<!-- edikt:compiled — generated by /edikt:gov:compile, do not edit manually -->
<!-- compiled_by: edikt v0.2.3 -->
<!-- compiled_at: 2026-04-09T10:30:00Z -->

Three fields, three purposes:

• compile_schema_version (YAML, enforced) — identifies the output format contract. 1 = v0.1.x flat governance, 2 = v0.2.x topic-grouped rule files. /edikt:doctor checks it against the constant declared in commands/gov/compile.md and recommends /edikt:gov:compile only when the format has actually changed.
• compiled_by (HTML comment, informational) — which edikt version ran compile. Diagnostic only, never enforced.
• compiled_at (HTML comment, informational) — ISO8601 timestamp. Diagnostic only, never enforced.

Consequences:

• No more false-positive staleness warnings on point releases. Users only see "regenerate governance" when the compile schema actually changed.
• Point releases can ship bug fixes without implying anything about compile output compatibility.
• /edikt:doctor gets smarter about stale governance detection.
• /edikt:upgrade has a new step that checks the project's schema version against the installed compile schema and recommends (but does not auto-run) regeneration when they diverge.
• Dogfooding stops hand-editing governance.md's version field. The dogfood file now uses the new format honestly.

Installer UX fixes

Three bug reports from real installs, all fixed in the same release.

• No prompt on curl | bash. The interactive "global vs project" prompt was skipped silently when stdin was a pipe (the common curl -fsSL ... | bash invocation). Now the installer reads from /dev/tty when available, so the prompt fires even when stdin is consumed by the curl pipe. Falls back to --global only when there's no TTY at all (CI, fully redirected).
• Commands duplicated across global and project locations. When a user installed globally in a directory that already had a project-local edikt install (either from a prior --project run, or from the dogfood repo itself), Claude Code ended up loading commands from both ~/.claude/commands/edikt/ and .claude/commands/edikt/, producing duplicates in the skill list. The installer now detects this condition at startup and emits a yellow warning pointing at the exact paths and the rm -rf to clean them up. Never auto-deletes.
• No detection of existing install before project install. If a user ran install.sh --project in a directory where ~/.edikt/VERSION already existed, the two installs would silently overlap. Same detection now fires a warning for this case too. Both detection paths share the same HAS_GLOBAL / HAS_PROJECT flags.
• New test scenarios in test/test-install-e2e.sh — scenarios 6 and 7 cover the duplication-warning paths (6 = global install with leftover project files; 7 = project install with existing global install). Total scenarios now: 7. Total assertions: 28.

Tests

• New test/test-v023-regressions.sh (21 assertions) — verifies ADR-007 exists, COMPILE_SCHEMA_VERSION is declared in compile.md, output templates emit the new format, doctor.md checks the schema version, upgrade.md documents the migration step, and the dogfood governance file matches the constant.
• test-e2e.sh version check refactored — no longer enforces GOV_VER == FILE_VER. Instead it validates that compile_schema_version in the dogfood governance file matches the COMPILE_SCHEMA_VERSION constant in commands/gov/compile.md.

v0.2.2

Critical bug-fix release. The v0.2.1 installer was silently broken on the v0.1.x → v0.2.x upgrade path.

Installer: upgrade from v0.1.x was silently broken

• ((BACKUP_COUNT++)) under set -euo pipefail killed the installer on the first backup. Postfix ++ returns the pre-increment value (0 on the first call), which bash's set -e treats as a failure and exits the script. Symptoms: the cleanup loop removed nothing, the new namespaced commands were never installed, old flat files stayed in place, and the installer exited without any error message. This shipped in v0.2.1 and affected everyone upgrading from v0.1.x via curl | bash. Fixed by using BACKUP_COUNT=$((BACKUP_COUNT + 1)).
• New integration test (test/test-install-e2e.sh) — 22 assertions across five scenarios: fresh install, upgrade from v0.1.x, user-customized file preservation, network failure abort, and repeated-install idempotency. Shims curl with a mock that serves files from the local repo, so the full install.sh runs end-to-end against a fake $HOME in /tmp. This is the test we wished existed before v0.2.0 shipped — it caught the v0.2.1 regression immediately.

/edikt:upgrade: migrate v0.1.x command references

• New step 5 in /edikt:upgrade: rewrite old flat command references in project files to their new namespaced equivalents. Projects initialized with v0.1.x have hardcoded references to /edikt:adr, /edikt:plan, /edikt:compile, etc. in their CLAUDE.md managed block and in compiled rule packs. Previously, /edikt:upgrade only migrated the sentinel format (HTML → visible) and left the content inside the sentinels untouched. Now upgrade runs a targeted string-replace across all 15 moved commands, scoped to edikt-owned content only (the CLAUDE.md managed block and rule pack files marked with edikt:generated or edikt:compiled). User content outside the managed blocks is never touched.
• Idempotent and safe: the instruction tells Claude to match only occurrences NOT already followed by :, using surrounding context (backticks, punctuation, end-of-line) for disambiguation. Running upgrade twice is a no-op.