TierDecay v0.5.0

Every agent, production Linux: the same posterior and the same deterministic
engine now drive OpenAI Codex and Google Antigravity natively, any MCP client
over stdio, and CI pipelines through a health gate.

Added

• OpenAI Codex adapter (install.sh codex): AGENTS.md, four roles in
  .codex/agents/ bound by model_reasoning_effort (xhigh / high /
  medium / low) with matching sandboxes, the MCP advisor in
  .codex/config.toml, a PreToolUse guard on apply_patch and Bash
  scoped to executor roles (.codex/hooks.json), and single-session
  profiles tierdecay-t0…t3.
• Google Antigravity adapter (install.sh antigravity): an always-on
  workspace rule, four subagents in .agents/agents/ (pro for T3/T2,
  flash for T1/T0, executors sandboxed), and .agents/mcp_config.json.
• Shared Agent Skills (core/agent-skills/: tierdecay-routing,
  tierdecay-distill, tierdecay-execution) installed to .agents/skills/
  for both; the installer records co-ownership so uninstalling one target
  keeps them for the other.
• tierdecay mcp: an MCP server over stdio with tierdecay_route,
  tierdecay_rubric, tierdecay_playbook, tierdecay_status,
  tierdecay_export, tierdecay_doctor, and
  tierdecay_validate_observation; tierdecay_record only with
  --allow-ledger-append true. Speaks the stateless 2026-07-28 protocol
  (server/discover, per-request version in _meta, resultType,
  cacheable tools/list, error -32022 with the supported versions) and the
  initialize handshake of 2025-11-25, 2025-06-18, 2025-03-26, and
  2024-11-05.
• tierdecay doctor: read-only health checks (Node version, ledger and
  playbook parse, 150-line cap, world-writable state, MODELS.md, router
  configuration, guard executable, owed bookkeeping, entries without
  epoch:); exit 1 on any failure.
• tierdecay observe --append LEDGER: validated, locked (O_EXCL, stale
  after 30 s, timeout 10 s), duplicate-refusing, fsync + rename ledger
  append that preserves the file mode.
• tierdecay export --format codex|antigravity; --root, --version,
  tierdecay completion --shell bash; documented, stable exit codes.
• OCI image (Dockerfile): distroless nonroot, base images pinned by
  digest, verified in CI read-only and without network.
• GitHub Action (action.yml): uses: alebgl77/tierdecay@v0.5.0 runs
  doctor, writes a job summary, exposes healthy and report.
• Releases: tag-release.yml tags main when package.json carries a new
  version with a CHANGELOG section, after the full CI suite passes on that
  commit; release assets gain a CycloneDX SBOM covered by SHA256SUMS.
• Engineering diagrams (docs/diagrams/: reference architecture, routing
  decision, decay lifecycle) generated by scripts/build-diagrams.js;
  ROADMAP.md; docs/PRODUCTION.md.
• Tests: tests/test-production.js (MCP both eras, concurrent appends,
  locks, doctor, layouts) and tests/test-adapters.js (Codex and
  Antigravity schemas and bindings against the engine); installer and guard
  suites cover the new targets and Codex apply_patch payloads.

Changed

• The guard resolves the project from CLAUDE_PROJECT_DIR, then
  TIERDECAY_PROJECT_DIR, then the working directory, and understands Codex
  apply_patch envelopes; its Codex copy is generated and CI-checked.
• install.sh auto detects .codex/, .agents/rules/, .agents/agents/,
  and the codex, agy, and antigravity binaries; the codex binary now
  selects the native Codex target instead of the generic AGENTS.md.
• core/MODELS.md records the Codex (effort) and Antigravity (pro /
  flash) bindings.
• Dependabot also tracks the container base images.

TierDecay v0.4.0

[0.4.0] - 2026-10-01

Repositioned as the per-repo learning layer for native model routers rather
than a router of its own.

Added

• benchmarks/pilot-v1: first measurement with real models — 36 graded Opus
  and Sonnet executor runs plus 3 distillation runs on a controlled fixture
  with hidden acceptance tests, exact input-side billing from transcripts,
  task-paired bootstrap contrasts, and a replay of the protocol on the
  measured outcomes. Fast tier 0.66× frontier cost at equal acceptance;
  protocol replay 24% below always-frontier; the distilled entry itself not
  significantly cheaper than a cold fast-tier attempt. Scope and limits in
  RESULTS.md; CI validates the fixture.
• Claude Code plugin (plugins/tierdecay) and marketplace
  (.claude-plugin/marketplace.json): /plugin install tierdecay@tierdecay,
  /tierdecay:init, an executor-scoped PreToolUse guard, a SessionStart
  hook that loads the protocol only in opted-in projects, and tierdecay on
  the Bash PATH. Generated from the native adapter by
  scripts/build-plugin.js; CI fails if they drift.
• tierdecay status: per-class route, hits against the risk-gated
  requirement, and the bookkeeping owed (decay, recertification, PRIORS).
• tierdecay export: routing tables for Claude Code (agent, alias, effort)
  and Cursor (model or Auto goal), JSON, and Agent Skills compiled from live
  playbook entries (quarantined entries are pruned, foreign skills untouched).
• tierdecay bench: seeded-permutation replay with in-memory playbook
  evolution (hits, decays, quarantines, recertification), order spread, and
  static/oracle baselines.
• Recertification: entries carry epoch:; a binding change routes them at
  provenance (recertify) before any further descent.
• Effort as the second binding axis: oracle xhigh, heavy-executor
high, executor medium, scout low.

Changed

• Decay is confidence-gated: a downgrade needs 3 / 4 / 5 probe hits for
  risk 0 / 1 / 2 (80% one-sided Clopper–Pearson bound on the pass rate
  reaching 0.5 / 0.6 / 0.7); risk-3 classes never decay; entries without
  risk: count as risk 2. Previously 2 hits for every class.
• Policy, enforced by tests/test-model-policy.js: no tier is bound to the
  cheapest model family; the cheap end of the ladder is sonnet at lower
  effort.
• Cursor adapter maps tiers to the router's Auto goals instead of advising
  against Auto.
• CLI defaults fall back to .claude/routing-ledger.md and the native
  playbook skill when .tierdecay/ledger.md is absent.
• SPEC §4 records when distillation pays: where the lower tier fails or
  struggles without the entry.

Fixed

• The shipped playbook templates did not parse with the advisor (the entry
  format example was read as a malformed entry), so every CLI command failed
  on a fresh install. Fenced code blocks are now documentation, and the
  templates fence their example.
• The guard script forwards its arguments to Node safely under set -u on
  Bash 3.2.

v0.3.0

Added

• Optional deterministic local router with legacy, safe-default shadow,
  and explicit optimize policies; zero runtime dependencies and Markdown as
  the source of truth.
• Strict request/observation/decision/scenario schemas, exact-cell bounded
  statistics, fully loaded scoring, conservative one-step VOI, and fail-closed
  quarantine/floor handling.
• Read-only route, row-emitting observe, and sequential replay CLI
  commands with canonical hashes and explicit incomplete-outcome refusal.
• Cross-platform algorithmic regression suite and a reproducible synthetic
  fixture. No real-workload benchmark or universal savings claim is implied.

Changed

• Release archives ship the router and schemas. The installer additively ships
  its documentation and a disabled/null configuration without overwriting
  existing local state.

v0.2.1

Changed

• The native Claude Code policy now uses four roles with two aliases: opus
  for the orchestrator, oracle, and heavy executor; sonnet for the executor
  and read-only scout. Current docs and structural regression checks match.
• Installer, routing, guard, and model-policy regressions run on Ubuntu,
  macOS, and Windows (Git Bash). A stable Release readiness job requires
  every CI dependency to succeed, including the existing install matrix.
• Native installation and upgrade instructions now cover .tierdecay/MODELS.md,
  review and merge of sidecars, preservation of learned state and hardened
  permissions, and a manual active-hook smoke check after reloading agents.

Fixed

• Uninstall preserves an owned file when its recorded source is missing and
  relinquishes the selected target's ownership instead of aborting cleanup.
• Bash guard blocks literal .claude. / .tierdecay. references that can
  resolve to protected directories through Win32; other trailing-dot/space
  variants are blocked conservatively by the lexical check.
• The guard suite invokes a native Windows helper to verify the single-dot
  alias. Broader dots/spaces are lexical regressions, not claimed native
  normalization coverage. Platform skips are explicit; no live Claude Code
  integration is claimed.

v0.2.0

Added

• cline, goose, and windsurf adapters — each ships an AGENTS.md mapped
  to the tool's native model controls (Cline Plan/Act, Goose /plan planner
  model, Windsurf per-message model picker) — plus their install.sh cases.
  Built by dogfooding TierDecay on itself; the real routing ledger from that
  session is in examples/self-build/.

• cursor adapter — ships an AGENTS.md Cursor reads natively at the repo root
  and in nested subdirectories (or a Project Rule at .cursor/rules/tierdecay.mdc
  with alwaysApply: true), mapping tiers onto Cursor's per-conversation /
  per-surface model picker (Agent/Ask/Plan modes). Adds an install.sh case,
  .cursor/ auto-detection, and CI matrix + conformance coverage.

• install.sh flags: --help, --version, --dry-run (preview every write),
  --uninstall (removes context files, never touches learned state).

• Non-native installs now ship the full spec as .tierdecay/PROTOCOL.md, so
  class-signature discipline and the §5 invariants travel with every adapter.

• CI: an install-matrix job (ubuntu + macos × 8 targets) asserting install
  and idempotent re-install (learned state must survive); a conformance
  job (120-line caps, adapter↔installer parity, normative-token presence in
  every non-native adapter); an offline docs job (mermaid fence balance,
  internal link resolution); a release.yml workflow guarding
  tag↔CHANGELOG↔CITATION coherence; dependabot.yml for actions updates.

• Claude Code adapter: a PreToolUse guard hook
  (.claude/hooks/tierdecay-guard.sh) wired into both executors' frontmatter
  blocks executor calls referencing .claude/ or .tierdecay/ at the tool
  layer (Write/Edit/MultiEdit/NotebookEdit/Bash).

• core/MODELS.md — the single source of truth for tier→model bindings, and the
  only file in the tree allowed to name a model version. Installed to every
  target as .tierdecay/MODELS.md. A new model release is now a one-row edit
  here instead of a sweep across adapters, skills, and agent descriptions.

• CI conformance: a guard that fails the build if a versioned model string
  (claude-opus-5, Sonnet 4.6, …) appears anywhere outside core/MODELS.md,
  the changelog, or a historical ledger. This is the mechanism that keeps the
  tree from going stale at the next release; it caught a stale placeholder in
  the bug-report template on its first run.

• CI is now reusable by the release workflow, runs the installer, routing, and
  guard regression suites, and Shellchecks every shell script in the tree.

Changed

• Model bindings are now expressed as tiers + provider aliases, never version
  numbers. Adapters, skills, and agent descriptions name roles (frontier /
  strong workhorse / fast / cheapest) and bind through the opus, sonnet,
  and haiku aliases, which resolve to the latest model in each family at
  session start — so a new release is picked up with no edit. Current bindings:
  Claude Opus 5 (T3 and T2), Claude Sonnet 5 (T1), and Claude Haiku 4.5 (T0).
  examples/self-build/ keeps the model names that session actually ran on —
  it is a historical record, not a live binding.
• install.sh rewritten around non-destructive copy_safe/copy_tree
  helpers: one collision policy everywhere (sidecar *.tierdecay, pending
  sidecars preserved), no reliance on cp -n semantics.
• detect() now reads project signals (.claude/, .cursor/, .clinerules/,
  .windsurf/, .goosehints, GEMINI.md, CONVENTIONS.md, AGENTS.md)
  before machine-global binaries, and can resolve cursor/cline/goose/windsurf.
• SPEC: PROBE now explicitly outranks PRIORS while a live entry exists, and a
  downgrade rewrites the entry's provenance — the T3→T2→T1 iteration has an
  operational path; escalation trigger (2 failed acceptance runs = 1
  escalation) defined; ≤400 words recon cap and keep last 50 ledger
  retention lifted into the spec.
• All 6 non-native adapters now carry invariant §5.2 (quarantine on ANY
  acceptance failure), the escalation trigger, class-signature discipline, the
  any axis maxed → T3 clause, and the full APPROVE / APPROVE-WITH-NITS /
  BLOCK verdict vocabulary.
• Cline adapter: T0 recon explicitly assigned to Plan mode (read-only safety
  over model cost), resolving the tier-map contradiction.
• Release publication now requires the tagged commit to pass the full CI,
  validates strict SemVer and ancestry from main, and remains a draft until
  its archive and SHA256SUMS assets have both been attached and verified.
• All actions/checkout uses are pinned to an immutable commit SHA.

Deprecated

Removed

Security

• Claude Code adapter: SPEC §5 invariant 1 ("only the orchestrator writes
  state") is now enforced at the tool layer, not just in the prompt —
  executor and heavy-executor carry a PreToolUse guard hook
  (.claude/hooks/tierdecay-guard.sh) that blocks their calls referencing
  .claude/ or .tierdecay/, and settings.json ask-gates all remaining
  state writes behind human approval. CI verifies the guard's behaviour.
• README/SECURITY.md: the anti-poisoning FAQ no longer claims impossibility
  ("it can't write") — defenses are documented as explicit layers (protocol,
  tool-layer enforcement, human review) with the residual risk stated.
• SECURITY.md: new "Distribution and shared-repo surface" section — install
  from tagged releases verified against the SHA256SUMS asset (shipped from
  v0.1.0), and an explicit commit-vs-ignore policy choice for shared
  .tierdecay/ state (a committed playbook is a shared attack surface;
  review its diffs like code).

Fixed

• Guard hook false positives: the PreToolUse guard judged the entire
  tool payload, so any legitimate write whose content merely mentioned
  .claude/ or .tierdecay/ was blocked — including adding .tierdecay/ to
  .gitignore, the exact choice SECURITY.md recommends. File tools are now
  judged by their target path only; Bash is still judged by its command
  string. CI carries the false-positive regressions.
• release.yml now builds the release archive and its SHA256SUMS
  (sha256sum -c compatible, same format as the v0.1.0 assets) so future
  releases keep the verification contract documented in SECURITY.md, and
  guards that install.sh's VERSION constant matches the tag.
• Adapter READMEs showed a copy-pasteable install command
  (../../install.sh <target>) that fails from the repo being equipped;
  aligned on /path/to/tierdecay/install.sh <target>.
• install.sh could destroy learned state: the claude target's
  cp -rn … || cp -r … fallback silently overwrote an existing .claude/
  (routing ledger and playbook included) on GNU coreutils ≥ 9.2, where cp -n
  exits non-zero when skipping. Replaced with a guarded per-file walk through
  copy_safe — existing files are always preserved and a differing incoming
  version lands as a .tierdecay sidecar; regression-tested in CI (idempotence
  test + full install matrix).
• Quick-start commands no longer cd into the checkout (which guaranteed the
  installer's self-install guard would abort) and now list all 8 targets.
• CI "Every adapter is complete" check was vacuous (the *.md glob matched
  README.md itself); it now excludes the README and actually fails on a
  missing context file.
• adapter_request.yml: unquoted - Yes parsed as a YAML boolean, breaking
  the dropdown; quoted. Bug-report dropdown now lists all adapters.
• examples/self-build/playbook.md made SPEC-conformant (provenance rewritten
  to T1, hit counter reset after downgrade).
• Docs no longer call the Bash installer "POSIX".

TierDecay v0.1.0

TierDecay is a self-distilling model router for AI coding CLIs. Solve each problem class at the expensive model tier once; the orchestrator distills the decision (invariants, ordering, the trap) into a ≤15-line playbook entry; future occurrences of that class are probed one tier cheaper. Two probe passes drop the class's default tier permanently. The routing rubric is only a cold-start prior — a ledger of predicted-vs-executed tiers is the empirical posterior that overrides it in both directions.

No proxy. No daemon. No SDK. Just markdown and a protocol.

What's in 0.1.0

• Core spec (core/SPEC.md) — tool-agnostic rubric + routing/decay protocol
• Four adapters — Claude Code (native 4-agent pipeline), universal AGENTS.md (Codex CLI · Cursor · OpenCode · Copilot · Zed), Gemini CLI, Aider
• POSIX installer (install.sh) + ledger/playbook templates
• Full community-health set, CI (shellcheck + structure), and brand assets

Try it

git clone https://github.com/alebgl77/tierdecay && cd tierdecay
./install.sh <claude|agents|gemini|aider>   # or: ./install.sh auto

The health metric is the executed column of your ledger drifting toward the cheap tier over time. That drift is the product. Post your real decay curve — not ours.

MIT licensed. Adapters wanted — see CONTRIBUTING.