v1.7.3 — Interactive Update Prompt + Project Profile System

First release since v1.4.0. It rolls up everything from v1.4.1 through v1.7.3 — two big additions (Project Profile System, version freshness check), a versioned update log, and a round of test-driven hardening.

Highlights

🔔 Version freshness check (v1.7.0 → v1.7.3)

project-butler now tells you when your installed copy is behind upstream. Every invocation starts with a cached check (at most one git fetch per machine per day) comparing local HEAD to origin/main.

When you're behind, Claude Code asks once — and at most once every 24 hours:

project-butler is 3 commits behind upstream. Update now?
  › Update now       — pull the latest version right here
  › Remind me later  — ask again tomorrow
  › Stop reminding   — turn the check off

• Update now runs a fast-forward-only pull for you; on failure you get the manual command plus an HTTPS fallback. Nothing is ever pulled without you choosing it.
• The prompt follows your project's CLAUDE.md Language: setting (English / Chinese / bilingual).
• Cache is dual-keyed on a 24h window and the HEAD SHA, so the notice clears immediately after you update instead of lingering.
• SSH fetch is bounded by ConnectTimeout=5, so a blocked port 22 (corp network, firewalled region) fails in ~5s instead of hanging the skill for ~2 minutes.
• Silence permanently with PROJECT_BUTLER_NO_UPDATE_CHECK=1 (literal 1 only).

Reach limitation: this only protects installs from v1.7.0 onward. If you're on v1.6.x or earlier, pull once manually — cd ~/.claude/skills/project-butler && git pull — and future updates notify automatically.

🧭 Project Profile System (v1.5.2 → v1.6.0)

Setup is now profile-aware. Foundation Setup infers your project's shape from a natural-language description, generates project-specific foundation areas, and proposes Required / Recommended / Optional documents before creating anything.

• New profile state files: .claude/project-profile.json and .claude/profile-pending.json
• Normal Close records profile-impacting changes as pending debt; Full Close produces a Scope Plan before touching profile docs
• Bounded Foundation Repair with a repair queue, batch limits, and stop conditions
• Review queue escalation and stale-document detection
• continue, continue full context, and status all restore profile shape, document policies, pending updates, and review queue items
• Lightweight projects use maintenance.preference = "lightweight" — minimal docs, profile state still intact

🛠 Multi-tool compatibility (v1.7.1)

Update detection moved into a standalone scripts/check-update.sh so it's no longer Claude-Code-only.

• Claude Code: native, automatic
• Cursor: .cursor/rules/project-system.mdc, best-effort, manual update check
• Codex: AGENTS.md template mirroring the full core workflow, best-effort
• Support levels tracked in docs/test-reports/adapter-coverage-matrix.md

📓 Versioned update log (v1.5.0)

Pick a version style at setup — Semantic (v0.1.0), Codename (Project Name 0.1), Patch (Patch 1), or Date (2026.06.1) — and end session computes the next milestone version in that style. Your project's versioning is independent of project-butler's own.

Fixes and hardening (v1.7.2 and v1.4.1)

• Freshness check failed closed: when git fetch failed (offline / port 22 blocked), it silently reported "up to date" instead of falling back to the last SHA-valid cached count — it broke in exactly the environments it was built for. Fixed.
• Corrupt cache with a non-numeric last_check no longer leaks an arithmetic error to stderr.
• Profile evolution proposals can no longer narrate an unconfirmed pivot into generated_project_shape.
• Document archiving: generic filename keywords (notes, design, test, …) now defer to content analysis instead of mis-filing content-rich documents.
• Update log: patch-level significant changes in codename / patch / date styles are recorded as Minor instead of being dropped.
• File reorganization: moving a file now also fixes the moved file's own relative references, not just inbound ones.
• continue path resolution fixed for working directories containing non-alphanumeric characters.

Validation

• Version freshness check: live-validated 2026-06-20 (first install, cache hit, pull recovery, SSH fail-fast) and 2026-07-17 (interactive prompt, 24h throttle, language adaptation, --pull) — 5/5.
• Project Profile System: 6 use cases + 3 adversarial scenarios, plus module tests for file reorganization, document archiving, and update log.
• Known limit: the Step -1 check runs as a skill instruction, so it is best-effort — it can occasionally not fire. Run scripts/check-update.sh manually any time you want a definitive answer.

Full log: UPDATE_LOG.md