v0.4.0 — 2026-07-09

Release Notes

Self-contained vendor install with a full yf self update/install/uninstall
lifecycle and XDG dirs; a yf-plan lifecycle overhaul (intake-at-execute,
base-pinned branches, fingerprint re-review gate, ready-for-approval gate,
cascade-close on completion); a .yf/ config namespace with a minimal-local
profile; and bd 1.1.x certification.

Added

• Self-contained vendor install + yf self lifecycle (#55). yf is now
  primarily distributed via the curl | sh installer to ~/.local/bin (uv-style),
  with Homebrew kept as a secondary path. New yf self command surface:
  • yf self update — checks the latest GitHub release, downloads the host's
    yf-<triple>.tar.gz, verifies its sha256 against the release manifest, extracts
    it (pure-Rust flate2+tar), and atomically replaces the running binary
    (self-replace). Vendor installs only: it refuses on a Homebrew (Cellar) copy
    (directing you to brew upgrade) and on a from-build/unknown copy unless
    --force. --check reports availability without swapping.
  • yf self install --from-build [--release|--debug] [--build] [--force] — promotes
    a local cargo build to ~/.local/bin/yf for development (suppresses the upgrade
    nudge; yf self update --force round-trips back to a vendor release).
  • yf self uninstall — removes the binary, the yf-owned XDG dirs, and the
    installer's PATH line, never touching installed skills/rules.
• Post-update skills/rules refresh. After a successful yf self update, the new
  binary re-deploys user-scope skills/rules once per present surface (~/.claude,
  ~/.agents); --binary-only skips it. Fail-soft — a refresh failure never rolls
  back the binary swap.
• Upgrade-detection nudge. yf version / yf doctor print a throttled (24h),
  fail-open, vendor-only notice when a newer release exists. Opt out with
  YF_NO_UPDATE_CHECK=1; auto-skipped under CI.
• XDG directory layout. yf resolves config/cache/data/bin via an XDG layout on
  both Linux and macOS (honoring XDG_CONFIG_HOME / XDG_CACHE_HOME /
  XDG_DATA_HOME / XDG_BIN_HOME): receipt → ~/.config/yf, update-check cache →
  ~/.cache/yf, binary → ~/.local/bin.
• Preflight self-update offer (REQ-YF-PRE-009). On an ok verdict, yf preflight
  now folds a yf self update offer into instructions when a newer release is
  already known — vendor installs only, cache-only (it reads the shared
  ~/.cache/yf/update-check.json the throttled yf version/yf doctor nudge writes,
  so it adds no network latency to a skill invocation and is eventually
  consistent). The offer notes that yf self update also refreshes installed skill
  definitions/rules and that you likely need /reload-skills afterward. A build from
  a dirty working tree (surfaced as a -dirty suffix on yf version) is the
  first short-circuit and is never offered an update — it signals active local yf
  development.
• Preflight cache version-invalidation (REQ-YF-PRE-008, REQ-YF-SELF-007). Each
  .yf/<skill>/preflight.json is stamped with the generating yf version; a mismatch
  (or absent stamp) is a full cache miss that re-probes system deps + bd and re-runs
  the scaffold ensure. This is how yf self update invalidates preflight — the swapped
  binary reports a new version, so the next preflight re-validates from scratch with no
  explicit cache-clear.
• yf-plan ready-for-approval gate (plan-024, #69). A ready-for-approval status
  plus a ready-check verb gate the approval prompt on last-red-team = APPROVE AND
  audit-pass, so approval can't be granted over an un-reconciled review or a failing
  portability audit.
• yf-plan cascade-close on completion (plan-024, #73). A self-contained
  close_cascade.py wired into RECONCILE §6.4 closes container/epic beads when a plan
  completes — fail-loud on still-open children, treating a resolved gate as terminal.
• CONTRIBUTING.md — how to report yf-* skill defects (#75). Documents where to
  file, the report checklist, and anti-patterns (with #74 as the exemplar); linked from
  the README so GitHub surfaces it in the new-issue flow.
• Claude Code Optimization docs (plan-025, #80). New README section plus an expanded
  docs/recommended-settings.md (permissions block, tool disables, notification/upload/
  connector keys).

Changed

• yf-plan lifecycle rework — intake-at-execute (plan-021, #47 + #63 + #64). A
  predictable, worktree-default git model:
  • Intake-at-execute (#47). The plan-execute molecule is no longer poured at
    INTAKE; INTAKE now writes a content fingerprint, auto-commits the plan, and
    lands it. The pour moves to EXECUTE start, where one resume-scan-driven
    pour-once/resume gate replaces the old duplicate-pour + resume guards (epic
    absent → pour + atomic record-epic; present → resume).
  • Base-pinned named branches (#47). Planning runs in <plan-id>-development,
    execution in <plan-id>-execute cut from a pinned base (never ambient HEAD),
    with a landing-strategy config switch (main default | feature-branch) that
    drives both the execute base and the §6.1 merge target. Teardown deletes only
    <plan-id>-execute, preserving the feature branch under feature-branch.
  • Auto-commit at the plan→execute boundary (#63). New commit-plan verb makes a
    scoped, local-only commit (never pushes, refuses the default branch / detached
    HEAD fail-closed) — a GR-PLAN-003 carve-out so a fresh execute session inherits a
    committed base.
  • Content-fingerprint re-review gate (#64). Approval writes a **Fingerprint:**
    over the plan's content sections (excluding header fields, phase-log, reviews/,
    and ## Upstream Issues); editing reviewed content marks the plan stale-approved
    and blocks execute until re-review (or logged --force).
  • SPEC-first: REQ-PHASE-002/REQ-RESUME-001/REQ-RESUME-004, REQ-BRANCH-001..004,
    REQ-PLAN-034/040/054/055/064/065, REQ-PORT-040/041. A scratch-project Tier-2 test
    harness (skills/yf-plan/test-harness/) validates the modified skill; the installed
    copy is promoted (cargo build → yf skills install) only after the scratch smoke.
• cargo-dist installer retargeted to ~/.local/bin + .tar.gz. install-path
  moved from ~/.cargo/bin to ~/.local/bin (XDG), and unix-archive flipped from
  .tar.xz to .tar.gz so yf self update extracts with pure-Rust flate2 — no
  system tar/xz dependency on minimal Linux/container hosts.
• Install docs re-sequenced (#54, partial). README and the website install page
  now lead with curl | sh (Homebrew secondary) and document yf self …, the XDG
  dirs + env overrides, and the macOS browser-download xattr note.
• Mode-aware yf-beads-init wedged-migration repair (plan-020, #56). The
  wedged-schema-migration fix is now mode-aware. Server mode is unchanged
  (bd dolt stop → bd migrate schema → bd migrate); for embedded storage
  (.beads/embeddeddolt/, no Dolt server — where bd dolt stop errors and
  bd migrate schema fails against the dirty on-disk working set) repair now commits
  the working set first via a data-preserving native step (raw dolt add -A && dolt commit in the derived Dolt-repo dir; never reset --hard/--allow-empty; a clean
  tree is a no-op; falls back to bd dolt commit when dolt is absent). Mode is
  detected from .beads/metadata.json (dolt_mode, with a dolt-server.* filesystem
  fallback); the Dolt-repo path is derived (unique .dolt/-parent, guarded against
  zero/multiple candidates), never hardcoded. The verify remediation string is
  likewise mode-aware. SPEC: REQ-BINIT-011/REQ-BINIT-016, REQ-YF-PRE-007;
  BEADS_INIT.md rule → v1.0.3.
• bd 1.1.x certification + local-only remote hygiene (plan-022, #68 + #61). The
  beads skills are certified against bd 1.1.x (219 yf tests + 41 upstream tests green,
  FULL merged-state validation passing) and local-only remote handling is hardened.
• .yf/ config namespace + minimal-local profile (plan-023, #58 + #67 + #66 + #57).
  Per-skill config migrated to .yf/<skill>/config.local.json (legacy root dotfile
  migrated in, gitignore anchors collapsed; REQ-YF-MIGRATE-001, REQ-YF-PRE-004);
  read-only profile engine-mode drift detection with doctor --repair reporting the
  embedded engine-mode without migrating (REQ-YF-PRE-010, REQ-BINIT-025);
  interactions.jsonl gitignored in the repair top-up (REQ-BINIT-023); and the
  UPSTREAM_TRACKING Safety-invariant reworded routing-primary (REQ-BUP-032).
• Removed the transitional flat .yf/<short>.local.json config tier (#76). Now that
  the .yf/<skill>/config.local.json migration is ubiquitous, config resolution and
  migration drop the flat interim tier end to end — resolution is canonical subdir →
  legacy root dotfile only (revises REQ-YF-PRE-004, REQ-YF-MIGRATE-001).

Fixed

• yf-plan commit-plan failed on local-only beads repos (#71). commit-plan did
  an unconditional git add -- "${plan_dir}" .beads; where .beads/ is gitignored
  (gh-only interchange), the ignored pathspec made git add fail and blocked intake. The
  pathspec is now conditional (.beads/ added only when it exists and is not gitignored),
  surfacing a beads_note when skipped. SPEC: REQ-PLAN-064 local-only carve-out.
• change-validation FAST tier missed formatting drift (#45). The .rs FAST tier ran
  only cargo test, so cargo fmt drift slipped past local validation and failed only in
  CI (bit v0.3.2). A dedicated cargo-fmt FAST id (cargo fmt --all -- --check) now runs
  on *.rs/Cargo.toml edits; clippy stays FULL-only.
• change-validation engine resolver never fired on real installs (#74). yf-plan
validate-merged resolved the yf-change-validation engine at one hardcoded in-repo
  path, so every user- or .claude/.agents-scope install fell through to engine: none
  and the layer-(b) cross-plan safety net never ran. Resolution now mirrors the SKILL_DIR
  find precedence (user → project → cwd), searching in-tree source then install surfaces.

Install yf 0.4.0

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dixson3/yoshiko-flow/releases/download/v0.4.0/yf-installer.sh | sh

Install prebuilt binaries via Homebrew

brew install dixson3/tap/yf

Download yf 0.4.0

File	Platform	Checksum
yf-aarch64-apple-darwin.tar.gz	Apple Silicon macOS	checksum
yf-x86_64-apple-darwin.tar.gz	Intel macOS	checksum
yf-aarch64-unknown-linux-gnu.tar.gz	ARM64 Linux	checksum
yf-x86_64-unknown-linux-gnu.tar.gz	x64 Linux	checksum