v0.2.0 — context-loss recovery (/compact + /clear)

Headline

Refresh now fires immediately after the two moments an agent has just lost most of its working memory:

• /compact (or AutoCompact) — wired via the PostCompact hook, dropping a signal file the next refresh consumes (#30).
• /clear — sibling trigger via SessionStart with matcher: "clear", sharing the same signal file (#32).

These are the windows where re-injecting the brief gives the highest ROI. Cadence stays in place for everything else.

What install-hook wires now

Three event handlers in .claude/settings.json:

• UserPromptSubmit → revive refresh (cadence-gated emit)
• PostCompact → revive mark-compact (drops signal)
• SessionStart matcher=clear → revive mark-clear (drops same signal)

Idempotent: re-running install-hook adds only what's missing. revive doctor validates all three (and verifies the SessionStart matcher specifically — codex caught a false-positive in review where matcher=startup pointing at mark-clear would have passed).

Also since v0.1.19

• revive init now auto-fixes .gitignore so the documented ".revive/static.md is checked in" workflow actually works (#31). Handles .revive/, .revive/*, .*, and read-only .gitignore.
• README tagline rewrite (#31): "Your agent forgot the ADR you wrote 30 prompts ago."

Install / upgrade

curl -sSL https://raw.githubusercontent.com/justi/context-revive/main/install.sh | bash
revive install-hook              # adds the new PostCompact + SessionStart entries
revive doctor                    # confirm all three hooks

Existing users: install-hook is idempotent — running it after the upgrade adds only the new entries without touching the existing UserPromptSubmit one. Per-project .revive/static.md and the rest of settings.json are untouched.

Test surface

139 bats tests, full CI on every PR (shellcheck + bats).

v0.1.19 — revive doctor

Highlights

• revive doctor (#27): sanity-check the install in one command. Runs seven checks — git binary, git repo, jq, .revive/static.md exists, PURPOSE filled in (not placeholder), UserPromptSubmit hook wired in local or global settings.json, hook log present and under 1 MB. Exits 1 only on real blockers; WARN-only conditions are hints, not failures.
• Dogfood (#28): the repo now commits its own .revive/static.md, so revive doctor passes here. .gitignore un-ignores static.md so the documented "checked in" workflow actually works.

No behavior change

refresh / show / init / suggest / audit are byte-identical to v0.1.18.

Install / upgrade

curl -sSL https://raw.githubusercontent.com/justi/context-revive/main/install.sh | bash
revive doctor

Existing users: revive doctor is the recommended way to verify the upgrade landed cleanly. Per-project .revive/static.md and Claude Code hook settings are not touched.

v0.1.18 — CI + README rewrite

Highlights

• CI (#25): shellcheck + bats run on every push to main and every PR. 111-test suite, fixed test 71 to actually verify the stdout-only contract for revive suggest.
• README rewrite (#22): action-first structure (ruby_llm-contract style). 96-line core, fewer headings, examples up front.
• README audit (#24): every section verified against actual bin/revive behavior — no stale claims.
• Generic example (#23): replaced project-specific brief with a generic Go scheduler so the example travels.

No behavior change

bin/revive runtime is identical to v0.1.17 apart from a cosmetic ls *.gemspec | head → find -maxdepth 1 swap to satisfy shellcheck.

Install / upgrade

curl -sSL https://raw.githubusercontent.com/justi/context-revive/main/install.sh | bash

Existing users: re-run the same command — it overwrites ~/.local/bin/revive in place. .revive/static.md is untouched.

v0.1.17 — separate audit command

User insight on v0.1.16: bundling the audit pass inside the suggest prompt means the SAME agent session that generated the content also audits it. Two real failure modes:

1. Context saturation — by STEP 2's end, the agent's attention is spent. Scanning artefacts against a checklist in that window is noticeably worse than fresh.
2. Self-critique sycophancy — LLMs asked to audit own recent output in the same turn tend to rubber-stamp.

Fix in v0.1.17: revive audit is now its own command, printing a standalone prompt designed to be pasted into a FRESH agent session (new Claude Code session, /clear in existing, new Cursor tab, aider --restart, etc.).

Preserves the 'works with any agent' property — no Claude-CLI or provider headless-mode dependency.

Flow:

revive init
revive suggest | pbcopy    # paste → agent generates + edits file
revive audit   | pbcopy    # paste into FRESH session → agent audits + proposes missing bullets
revive show

Also bug-fixed: set -u empty-array on minimal repos caused audit to exit 1.

111/111 bats tests pass.

v0.1.16 — STEP 3 audit pass

Real-use feedback: even with v0.1.15's relaxed limits, first-pass LLM output on rich-architecture projects consistently misses specific classes of non-inferable facts (toolchain-specific invocations like .venv/bin/python, agent-skill-file discipline, workflow dichotomies like incremental vs full scan).

STEP 3 audit pass added to revive suggest prompt. After STEP 1 (preview) and STEP 2 (edit file), agent re-reads everything and scans against six commonly-missed categories:

1. Toolchain specifics — non-default invocations
2. Agent skill / knowledge-file discipline — .claude/skills/, .cursor/rules/ etc.
3. Workflow dichotomies — command pairs where misuse = silent drift
4. Privacy / OpSec — what must not leak to public content
5. Cross-ADR process rules — panel review, journal hooks, supersession chains
6. Convention collisions — shared labels across files that clash

STATIC-only: audit may consult DYNAMIC sections as signal but never edits them (they regenerate every refresh).

Anti-padding: if nothing substantive is missing, agent says Audit: no gaps found. and stops. User approves before any file extension.

107/107 bats tests pass (+5 new cases).

v0.1.15 — raise section limits

Real-use feedback on armillary exposed that the prompt's up to 5 INVARIANTS cap was artificial aesthetics, not a real budget limit. armillary has 9 canonical architectural rules (ADR 0001); agent was forced to drop 4.

Changes:

• DIFFERENTIATORS: up to 5 → up to 7
• INVARIANTS: up to 5 → as many as matter (typically 3-10), with explicit project-size heuristic
• GOTCHAS: 3-5 → as many as matter (typically 3-7)
• New guidance: real hook cap is 10,000 chars — don't self-censor when content warrants

Running revive suggest on rich-architecture projects now covers ALL canonical rules instead of a 5-item shortlist.

102/102 bats tests pass.

v0.1.14 — DIFFERENTIATORS section + PURPOSE requires business goals

Two changes driven by real-use feedback:

1. PURPOSE now requires business goals.
A gh-style marketing tagline (single sentence describing what the project does) was passing the old 'substantive' check and being preserved by revive suggest. But it doesn't tell an agent WHY the project exists or what success looks like. Updated spec requires all three: what + why (business goal / success criterion) + essential philosophy or hard constraint. Marketing taglines now classify as placeholder and get regenerated.

2. New STATIC section: DIFFERENTIATORS.
Captures competitive positioning and deliberate design choices that contradict obvious alternatives. Prevents agents from suggesting 'why not use X?' for an X you already evaluated and rejected.

Format: <alternative> → <our choice/rationale> or unlike X, we Y because Z.

Brief layout: PURPOSE → DIFFERENTIATORS → INVARIANTS → GOTCHAS.

Full integration: init scaffolds placeholder, init --force preserves user edits, show suppresses placeholder bullets, suggest generates as Deliverable 2.

100/100 bats tests pass (+7 new cases).

v0.1.13 — suggest generates PURPOSE

revive suggest now generates all three static sections — PURPOSE, INVARIANTS, GOTCHAS — instead of only INVARIANTS/GOTCHAS. Solves: deterministic first-sentence cap was too terse for projects with rich CLAUDE.md sections.

Key property: symmetric preservation. If a section already contains substantive human-curated content, it's preserved verbatim. Only placeholder sections are regenerated. Idempotent re-runs are safe.

93/93 bats tests pass. Three rounds of Codex review tightened the prompt — remaining edge cases (partial curation with scaffold-bullet still present, genuinely blank sections) are rare and flagged for v0.1.14.

v0.1.12 — robust comment body handling

Third and final round of Codex-caught fixes on the commit-body feature from v0.1.9.

v0.1.12 fixes:

• Comment-only lines inside a paragraph no longer terminate it prematurely. Line one\n<!-- mid --> \nLine two now correctly extracts Line one Line two.
• Inline HTML comments whose body contains > (e.g. <!-- x > 0 -->) are now stripped correctly via index-based scanning instead of a regex that stopped at the first >.

This completes the commit-body extraction feature started in v0.1.9. Three rounds of Codex review caught three separate regressions that unit tests missed — a textbook case for having an external reviewer loop.

87/87 bats tests pass (+3 new cases).

v0.1.11 — inline HTML comments preserve prose

Second Codex-caught regression on the v0.1.9 commit-body feature.

v0.1.10 skipped HTML comments too aggressively — it dropped any line containing <!--, so content-bearing lines like Fix parser crash <!-- closes #42 --> lost their prose.

Fix in v0.1.11: awk now strips only the <!-- ... --> pairs themselves, preserving prose on the same line. Multi-line comment blocks still consumed across line boundaries; markdown headings still skipped. Content-only lines, comment-only lines, and hybrid lines all extract correctly now.

84/84 bats tests pass (+3 new cases).