Release notes — v0.1.0¶
Released: 2026-05-07. Audience: operators evaluating
apothemfor production agent work; existing users adopting the inception line. Companion docs:CHANGELOG.md(line-item record) ·docs/positioning.md(full strategic frame).
§1. What this release is, structurally¶
apothem v0.1.0 is the inaugural public line of an artifact-ratification governance project distributed as a CLI binary. The release is not a prompt set, not a slash-command toolkit, not a system-prompt template, and not a model-selection harness. It is a rule corpus, and the binary is the packaging the corpus rides on.
The conventional framing of agent tooling treats the leverage point as the prose the operator hands the model. Under that framing, the recovery for a malformed emission is to edit the prompt and try again. The artifact the project distributes is the prompt set; everything else is auxiliary.
apothem rejects that framing.
The leverage point of an agent operating against a real codebase is the artifact the agent is about to emit — the source file about to be written, the commit about to land, the documentation page about to ship, the schema about to migrate, the configuration about to alter behavior. Once the artifact lands, it gets committed, reviewed, merged, deployed, cited by downstream artifacts, and inherited by future contributors. Its quality is a downstream-irreversible property the prompt cannot retroactively repair.
The discipline this release encodes is inversion: every emission of meaningful scope passes through a structured, ratified, mechanically-checked gate before it leaves the agent's hands. The gate enforces fifteen mandates spanning host-discovery, disclosure, ten quality dimensions, authority hygiene, expertise incorporation, option annotation, definitiveness, visual leverage, bidirectional binding, agile sprint apparatus, canonical layout, code craft, systemic participation, and production-readiness. Every gate failure is a structural finding the agent surfaces — never a silent degradation.
What changes about how an operator thinks: the question shifts from "what should I tell the agent?" to "which mandates constrain this emission, and what evidence does the gate require?". The shift is structural, not stylistic. The corpus is the long-tail asset; the binary is replaceable scaffolding.
The rest of this document walks the seven capabilities the v0.1.0 line ships, then frames the three load-bearing pillars (mandate registry · canonical-channel discipline · cognitive-identity taxonomy) that bind the corpus into a coherent governance regime.
§2. Capabilities shipped in v0.1.0¶
The seven capabilities below are the headline surface of v0.1.0. The full line-item record lives at CHANGELOG.md; this section frames each capability at the level an evaluator decides whether to adopt the line.
§2.1 Plan-pipeline framework¶
Five /plan-* slash commands compose an end-to-end prose-to-execution lifecycle: /plan-spec forges free-form prose into a spec-grade specification through six transformation phases under four operational disciplines; /plan-generate produces a Master Plan Suite from the authored spec; /plan-review runs a forensic blind audit emitting scorecards across nine review dimensions; /plan-execute dispatches per-task execution with per-task commits, mandatory between-stage compaction, and a continuous-execution transition; /plan-status reports read-only progress with a health grade. The five commands connect through a typed Handoff Manifest that carries scorecards, attestations, and pre-emission gate state across the pipeline. The framework sits at the boundary where a non-trivial multi-step engineering task enters the agent's surface; it transforms raw operator intent into a sequenced, gated, audit-trail-bearing implementation plan.
§2.2 Fifteen-mandate outward-conformity registry¶
Every host-project artifact passes a fifteen-bar pre-emission gate covering host-project agnosticism (M1), editorial discipline (M2), ten-dimension quality (M3), self-application (M4), authority hygiene (M5), expertise incorporation (M6), option annotation (M7), definitiveness (M8), visual leverage (M9), bidirectional binding (M10), agile sprints (M11), reporting and canonical layout (M12), code craft (M13), ecosystem systemicity (M14), and production-ready discipline (M15). The mechanical fraction of the gate (M2 / M5 / M7 / M8 / M10 / M13 / M15) is enforced by matchers under src/apothem/conformity/*-grep.py wired into PreToolUse Write/Edit hooks; the reasoned fraction (M1 / M3 / M6 / M9 / M11 / M12 / M14) is evaluated by the operating agent and recorded in a YAML attestation block per artifact emission. Gate failure on any single bar blocks emission; the artifact is revised and re-gated until every bar passes.
§2.3 Canonical-channel input discipline¶
Every operator-volitional decision routes through the structured AskUserQuestion invocation surface. Each invocation carries a three-segment option-annotation body (rationale: · recommendation: · default-pointer:); a closed four-value recommendation taxonomy (recommended · acceptable · discouraged · destructive-no-default) with a concrete-driver citation requirement on every non-neutral recommendation; a label-postfix bidirectional bind that surfaces the recommended option visually; and a per-file destructive-op floor that forbids batched delete / rename / move / overwrite-without-retention / revert-uncommitted invocations. Free-form prose questions as primary input are forbidden ecosystem-wide. Seven heuristic matchers (H1–H7) sweep every governed-core surface for drift; HIGH-severity findings block the airtightness composite gate.
§2.4 Cognitive-identity taxonomy¶
Five sequential cognitive filters (Obvious Purge · Domain Exile · Inversion Press · Combinatorial Explosion · Aesthetic Demand) and six on-detection ideation techniques (Historical Saboteur · Constraint Paradox · Living Systems Lens · Second-Order Narrative · Villain Frame · 100-Year Zoom) govern every non-trivial decision surface. A seven-axs-of-breadth taxonomy (Architecture · Concurrency · Performance · Security · Testing · Tooling · Observability) names the axs every non-trivial decision attests against. The taxonomy binds to a Senior Software Architect role with strict SOLID enforcement, modern type-hinting discipline, and clean-architecture layering. The discipline is not a tone-setter — it is the creative-architecture surface that prevents formulaic agent output and surfaces structurally novel framings the operator can act on.
§2.5 Tier-3 multi-platform packaged distribution across eight surfaces¶
Operator-facing one-line install across eight distribution surfaces: GitHub Release tarballs (darwin · linux · windows; cosign-signed via OIDC keyless), PyPI wheel + sdist (trusted-publisher OIDC; SHA-256 manifest), Homebrew tap with bottle workflow, Scoop bucket, winget manifest set with winget-releaser automation, AUR PKGBUILD with SSH-key sync, and FPM-built .deb + .rpm packages. Each surface ships with a smoke test and a CI workflow whose every uses: reference is commit-pinned by 40-character SHA. The eight-surface matrix is the production-readiness floor for an OS-agnostic CLI: macOS · Linux · Windows native package managers all carry a first-party install path, and the tarball channel covers the residual surface.
§2.6 Modern visibility surface¶
A hybrid hexagonal three-layer architecture logo ships with an animated SVG variant, dark-mode adaptation, and a full raster set (256×256 PNG fallback, multi-frame favicon, Open Graph banner). A modern centered README header carries the logo, tagline, dynamic badge row, nav strip, and horizontal rule. A documentation site at apothem.ahmedgad.com serves install / update / uninstall scripts and the rendered changelog. The visibility surface is not decoration — it is the discovery layer through which an evaluator forms a first-look judgment, and it carries the same rigor as the corpus it advertises.
§2.7 Production-ready change-set discipline with paired multi-OS surfaces¶
Every change ships tests + documentation + CHANGELOG.md entry + Conventional-Commits commit + GPG-signed tag + CI green in the same change-set. Paired install / update / uninstall scripts at scripts/installer/ (install.{sh,ps1} · update.{sh,ps1} · uninstall.{sh,ps1}) are idempotent, prerequisite-checked, and configurable via environment variables. The auto-update tool at scripts/dev/auto_update.py is read-only by default with an explicit --apply flag for the destructive path. Uninstall paths default to a timestamped backup with a refusal on unsafe targets. The discipline closes the operator-experience loop: install in seconds, update in seconds, uninstall in seconds, on macOS · Linux · Windows.
§3. Strategic positioning¶
The full strategic frame lives at docs/positioning.md. This section surfaces three threads from that document the v0.1.0 release operationalizes end-to-end.
§3.1 The mandate registry is the corpus¶
The fifteen mandates (M1–M15) are not aspirational bullets; they are rules with path-filtered scopes, body specifications, and mechanical or reasoned enforcement paths. Every mandate has a canonical specification under src/apothem/rules/<name>.md; the heaviest carry path-filtered companion sub-rules under src/apothem/rules/<name>-<aspect>.md for the operational depth. The registry is the load-bearing surface — adopting apothem is adopting the registry; the binary is the packaging.
§3.2 The canonical channel inverts the input surface¶
AskUserQuestion is the sole sanctioned input channel. The shift from free-form conversational prompts to a structured option-annotation surface is the input-side analog of the artifact-ratification gate on the output side: every operator-volitional decision is named, framed, recommended with rationale, and either resolved through the canonical channel or recorded as a fallback-to-recommended finding. The discipline cures the silent-pick failure mode that plagues conversational agents — every meaningful choice the agent would otherwise make silently is surfaced for ratification.
§3.3 The cognitive-identity taxonomy is the creative-architecture surface¶
The five filters and six ideation techniques are not stylistic add-ons. The Obvious Purge (Filter 1) and Aesthetic Demand (Filter 5) are always-on for every substantive output; the Domain Exile · Inversion Press · Combinatorial Explosion (Filters 2–4) activate on non-trivial decisions. The six ideation techniques fire on detection signals — recurring failure patterns, over-constrained solution spaces, accommodating proposals, century-spanning framings. The taxonomy is the surface that prevents the agent from collapsing to formulaic output under load and gives the operator a creative-architecture leverage point distinct from prompt-tuning.
§4. Adoption and next steps¶
The evaluation mode is clone and read. The corpus is small enough to inspect in an evening; the rule files are self-contained and cross-referenced; every claim in these release notes resolves to an artifact at a named path. The README's Install section names the one-line install for every supported OS surface; the runbooks under docs/runbooks/ cover the day-to-day operational surface (Pages enablement · release cycle · release recovery).
The v0.1.0 line is the inception release. Subsequent v0.N.0 lines will add capabilities while preserving the fifteen-mandate floor; the corpus is the stable surface the binary delivers.
For the line-item record of every change shipped in v0.1.0, see CHANGELOG.md.
For the full strategic frame, see docs/positioning.md.