[Extension]: Update AEE catalog entry to v1.4.0 #4937

Extension ID

aee

Extension Name

Applied Epistemic Engineering

Version

1.4.0

Description

Checks the claims in a spec-driven project against their evidence at every stage, and shows plainly what is verified, what is not, and what remains not understood.

Author

ElectroHire

Repository URL

https://github.com/electrohire/spec-kit-aee

Download URL

https://github.com/electrohire/spec-kit-aee/archive/refs/tags/v1.4.0.zip

License

MIT

Homepage (optional)

https://github.com/electrohire/spec-kit-aee

Documentation URL (optional)

https://github.com/electrohire/spec-kit-aee#readme

Changelog URL (optional)

https://github.com/electrohire/spec-kit-aee/blob/main/CHANGELOG.md

Required Spec Kit Version

=1.0.0,<2

Required Tools (optional)

• python (>=3.11) — required
• aee CLI — the Applied Epistemic Engineering engine (>=1.5.0,<2), installed from PyPI as applied-epistemic-engineering; 1.5.0 is the realigned engine (claim life-cycle stages, stage-capped reported statuses, lane-paired outcomes, not_understood) and the runner refuses an out-of-range engine at startup — required
• spec-kit-evaluator (>=1.0.0,<2) — Spec Kit extension implementing the Evaluator Contract — required companion: AEE is one evaluator among many, and its results are composed through this common evaluator so every evaluator's output is handled the same way; the runner's assess refuses (exit 2) when it is not installed in the project
• rtk — optional token-economy tool; every workflow degrades gracefully when it is absent
• headroom — optional token-economy tool; every workflow degrades gracefully when it is absent
• token-router — optional token-economy tool; every workflow degrades gracefully when it is absent
• ollama — optional; used only by the optional token-economy routing

Number of Commands

10 (speckit.aee.draft-claims, speckit.aee.assess, speckit.aee.challenge, speckit.aee.trace, speckit.aee.verify, speckit.aee.gate, speckit.aee.review, speckit.aee.gaps, speckit.aee.route-evidence, speckit.aee.report-savings)

Number of Hooks (optional)

5 (after_specify, after_plan, after_tasks, after_implement, after_verify)

Tags

epistemics, evidence, provenance, uncertainty, governance

Key Features

• Draft atomic claims from a spec's requirements for human ratification; drafts are born draft and are never upgraded by the tool (new command in 1.3.0)
• Assess claims against their evidence and show, for each claim, the life-cycle stage it has actually reached — created, checked, explained, accepted, digested — with reported status capped by that stage
• Ships as one system with the common Evaluator extension (a required companion): AEE's results are composed through it, so every evaluator's output is handled consistently rather than by each tool's own choice
• Report machine verification and human acceptance side by side as a pair, never merged into one number, plus a plain statement of what remains not understood
• Challenge claims on atomicity, boundaries, falsifiability, dependencies, and evidence independence
• Attach policy gates to assessment: per-claim accept / challenge / abstain verdicts with corroboration and forced-abstention rules, and measured per-source reliability blended into scoring
• Render the claim dependency graph and inspect where each claim's support comes from
• Verify the tamper-evident evidence ledger, without claiming that its contents are true
• Apply a CI-friendly decision gate to an assessment
• Diff two assessments into a materiality-filtered review queue (speckit.aee.review)
• Generate and update the gap register from a verification matrix and test evidence
• Route oversized evidence into raw slices for the gates, with token-savings figures that are measured, never estimated

Testing Checklist

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details

Install test: the v1.4.0 archive was installed from the download URL itself into a fresh Spec Kit project and exercised both ways the pair can be installed: with the Evaluator extension present, assess runs and emits its Evaluator Contract result for composition; with the Evaluator extension absent, assess refuses with exit 2, names the missing extension and how to install it, and writes nothing. The archive itself was also downloaded and parsed directly: its extension.yml reads id aee, version 1.4.0, spec-kit-evaluator declared required: true at >=1.0.0,<2, 10 command files under commands/, 5 hooks, README.md and LICENSE at the root.
Test suite: the extension repository's suite passes against the real AEE engine 1.5.0, and check_install.py now exercises the evaluator-missing refusal end to end (Evaluator extension removed → assess exits 2 naming it); the release PR's CI was green on the repository's protected main.
What changed in v1.4.0 vs v1.3.0: one design correction (the repository's specs/005-evaluator-required). In 1.3.0 the Evaluator extension was declared optional and only the contract was required, which made consistent handling of evaluator results a choice each project could skip. In 1.4.0 the Evaluator extension is a required companion — declared required: true in extension.yml and enforced by the runner — because AEE is one evaluator among many by design, and its results are composed through the common evaluator so every evaluator's output is handled the same way. The pair is one system. Nothing else changed: same 10 commands, same engine floor (>=1.5.0,<2), same Spec Kit range (>=1.0.0,<2).

Example Usage

# Install the engine the extension drives
python -m pip install "applied-epistemic-engineering>=1.5.0,<2"

# Install the extension pair (the Evaluator extension is a required companion)
specify extension add aee --from https://github.com/electrohire/spec-kit-aee/archive/refs/tags/v1.4.0.zip
specify extension add evaluator --from https://github.com/electrohire/spec-kit-evaluator/archive/refs/tags/v1.1.0.zip

# Draft ratifiable claims from your spec, then assess them
/speckit.aee.draft-claims
/speckit.aee.assess phase=after_specify artifact=specs/001-search/spec.md

Proposed Catalog Entry

{
  "aee": {
    "name": "Applied Epistemic Engineering",
    "id": "aee",
    "description": "Checks the claims in a spec-driven project against their evidence at every stage, and shows plainly what is verified, what is not, and what remains not understood.",
    "author": "ElectroHire",
    "version": "1.4.0",
    "download_url": "https://github.com/electrohire/spec-kit-aee/archive/refs/tags/v1.4.0.zip",
    "repository": "https://github.com/electrohire/spec-kit-aee",
    "homepage": "https://github.com/electrohire/spec-kit-aee",
    "documentation": "https://github.com/electrohire/spec-kit-aee#readme",
    "changelog": "https://github.com/electrohire/spec-kit-aee/blob/main/CHANGELOG.md",
    "license": "MIT",
    "category": "process",
    "effect": "read-write",
    "requires": {
      "speckit_version": ">=1.0.0,<2",
      "tools": [
        { "name": "python", "version": ">=3.11", "required": true },
        { "name": "aee", "version": ">=1.5.0,<2", "required": true },
        { "name": "spec-kit-evaluator", "version": ">=1.0.0,<2", "required": true },
        { "name": "rtk", "required": false },
        { "name": "headroom", "required": false },
        { "name": "token-router", "required": false },
        { "name": "ollama", "required": false }
      ]
    },
    "provides": {
      "commands": 10,
      "hooks": 5
    },
    "tags": ["epistemics", "evidence", "provenance", "uncertainty", "governance"],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "2026-09-15T00:00:00Z",
    "updated_at": "2026-10-12T00:00:00Z"
  }
}

Additional Context

Note for maintainers: this updates the existing catalog entry for the AEE extension (v1.2.0 → v1.4.0). It supersedes #4935 (the v1.3.0 update filed earlier today), which was closed unvalidated after a design correction shipped as v1.4.0; the v1.2.0 update was #4890 (merged via PR #4895). It is not a duplicate.

What changed in the entry, so the diff is easy to review:

• Version 1.2.0 → 1.4.0; commands 9 → 10 (adds speckit.aee.draft-claims, shipped in 1.3.0); hooks unchanged at 5.
• requires.speckit_version >=1.0.0 → >=1.0.0,<2, matching the released extension.yml.
• aee engine floor >=1.4.0,<2 → >=1.5.0,<2. Engine 1.5.0 is the realigned engine (life-cycle stages, stage-capped reported statuses, lane-paired outcomes, not_understood); the extension's runner refuses an out-of-range engine at startup rather than scoring with it.
• spec-kit-evaluator stays required: true — the same value the current (v1.2.0-era) catalog entry carries. The intermediate v1.3.0 release declared it optional ([Extension]: Update AEE catalog entry to v1.3.0 #4935); v1.4.0 corrects that as a design decision: AEE is one evaluator among many, and its results are composed through the common Evaluator extension so every evaluator's output is handled consistently — consistency by construction, not by each project's choice. The runner now enforces the pairing: assess refuses (exit 2) when the Evaluator extension is not installed.
• No sha256 is submitted, as with [Extension]: Update AEE catalog entry to v1.2.0 #4890; the catalog may record the digest validation computes for the v1.4.0 archive. The v1.4.0 tag will not be moved or recreated.

Links:

• Extension release: https://github.com/electrohire/spec-kit-aee/releases/tag/v1.4.0
• Engine release (the floor): https://github.com/electrohire/applied-epistemic-engineering/releases/tag/v1.5.0 — also on PyPI as applied-epistemic-engineering==1.5.0
• Evaluator release (the required companion): https://github.com/electrohire/spec-kit-evaluator/releases/tag/v1.1.0
• The v1.4.0 archive at the download URL above returns HTTP 200, and its extension.yml parses to id aee, version 1.4.0, spec-kit-evaluator required: true, 10 command files, 5 hooks.