den-refresh · v1.0.0 · 2026-10-19 · sha256 4c6ae50b24dfd91e

den-refresh v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/4c6ae50b24dfd91e.

---
name: den-refresh
description: >-
Use when an already-scaffolded project is behind the framework — a drift notice appeared, a new
ai-badger version shipped, or the user asks to "refresh"/"update ai-badger". Reports what
changed, backs up .ai-badger/, and re-scaffolds from the project's existing config.
version: 1.0.0
author: ai-badger
license: MIT
platforms: [linux, macos, windows]
scope: default
metadata:
hermes:
tags: [scaffolding, drift, upgrade, refresh]
related_skills: [welcome-ai-badger, feed-badger]
---

# den-refresh

Pulls framework updates from the ai-badger catalog into a project that was
already scaffolded. **The script does all mechanical work; you (the agent)
present the report and help the user review the diff.**

This is the update direction of the framework: framework → project (update).
For initial setup use `welcome-ai-badger`; to contribute back use `feed-badger`.

## Responsibility split

- **Script (mechanical):** `refresh.py` validates prerequisites (config.json,
manifest.json), runs drift detection, re-scaffolds with the existing config,
and emits a JSON report. Skills with extensions (e.g., `task` with
`github`/`hermes` extensions) are re-scaffolded and their extensions
re-embedded automatically.
- **You (creative only):** present the report, help the user review what
changed, and offer to commit or discard. There is no config authoring, no
stack detection, no plugin scope prompt — those belong to `welcome-ai-badger`.

## Prerequisites

- Project has `.ai-badger/config.json` and `.ai-badger/manifest.json` (it was
scaffolded by `welcome-ai-badger`)
- An ai-badger framework checkout is accessible (`$AI_BADGER`)

## Flow

1. **Run refresh.** From the target repo root:
```bash
python3 "$AI_BADGER/features/common/skills/den-refresh/scripts/refresh.py" --target . --root "$AI_BADGER"
```
Add `--prune-cache` or `--prune-namespaces` only when the user has asked for it (steps 3
and 3c) — both delete from the user's home directory. Add `--force` only
as recovery (see Error Recovery) — it re-scaffolds unconditionally, bypassing every drift
signal.
This:
- Validates that config.json and manifest.json exist
- Reads the manifest to extract scaffolded skill names
- Runs drift detection against the framework's current content
- If drift is found, re-scaffolds using the existing config.json
- Outputs a JSON report with drift details and scaffold notes

Exit codes: 0 = success (up to date or changes applied), 2 = error (missing
config/manifest, invalid config).

2. **Review the report.** The JSON output includes:
- `frameworkVersion` — the version in config.json vs. the framework's, plus the version
that actually wrote `manifest.json`. config.json advances only when a re-scaffold ran
- `drift.changed` — framework sources that have moved ahead of what this project holds
- `drift.removed` — scaffolded files whose framework source no longer exists
- `drift.orphaned` — entries whose stack this project no longer lists in `config.stacks`.
The framework still ships them; this project stopped asking. The re-scaffold prunes them,
leaving anything edited in place with a note
- `drift.versionChanged` — the version alone moved; it is stamped into manifest.json and
every generated agent file, so those are stale even when no content changed
- `drift.locallyModified` — skills this project edited in place. Not framework drift, but
a re-scaffold overwrites them; move anything worth keeping into `project-local.md`
- `drift.skipped` — directory entries from a manifest written before source hashing
existed. Nothing records what the framework looked like, so they cannot be compared;
a re-scaffold makes them comparable
- `drift.newItems` — catalog items the project has never scaffolded, including ones
added to the framework's always-on `common` stack after this project was set up
- `drift.configChanged` — `null` unless config.json itself no longer matches what the
last scaffold was built from (an `exclude`, `commands`, `stacks`, `agents` or
`personaRouting` edit). Present as `{"recorded": ..., "current": ...}`; `recorded: null`
means this manifest predates the field and self-heals on this one re-scaffold
- `drift.proseReview` — the config's free-form prose (`project.summary`, `project.domain`),
re-rendered verbatim into the managed agent files on every scaffold and checked by no
fingerprint, so it goes stale silently. Each entry names the `configKey`, the template
`slot` it fills, the `value` as written, and carries the note "human-written — review
for staleness". Present them to the operator for review; never treat them as drift —
a re-scaffold cannot freshen prose, only re-render it, and config.json is project-owned
- `newStacks` — stacks detectable in the target but missing from config. Advisory only:
it never triggers a re-scaffold, so non-empty `newStacks` alongside `reScaffolded: false`
is the expected shape, not a contradiction
- `reScaffolded` — whether a re-scaffold was performed
- `projectIdWarning` — present only when the project-id step warned: ai-raccoon's id lookup
or registration failed, several bank projects share this repo's name, or the reply was
unusable. The id file is still minted or kept; the warning names the command to rerun
after a human resolves it (ai-raccoon 1.57.0's `project id` verbs; ADR-0036)
- `note` — present only when config.json and the framework disagree on the version and no
re-scaffold ran; the generated files were not rewritten, so say so rather than reporting green
- `scaffold` — if re-scaffolded: entry count, refreshed skill names, notes
- `frameworkCopies` — present only when more than one tree on the machine claims to be
ai-badger, or when `~/.ai-badger/framework` exists. `competing` names the path, version
and owner of each; `cache` reports what happened to `~/.ai-badger/framework`
(`reported` by default, `removed` with `--prune-cache`, `refused` with the reason)
- `skillUsage` — which delivered skills this project was observed using, so unused ones can
be pruned from the listing budget (see step 3b). `used` / `unused` / `cannotTell`, plus the
`window` the claim rests on, the `channels` that answered, and the `limits` of both
- `hermesNamespaces` — present only when every ai-badger symlink in a
`~/.hermes/skills/<project>/` directory is dangling: that project's `.ai-badger/skills/`
tree is gone. Every project's namespace is swept, not just this one (see step 3c). Each
entry carries `path`, `links` (dead links ai-badger placed), `kept` (entries it did not —
a non-zero `kept` means the directory itself survives the prune), the `target` that no
longer exists, and `status` (`reported` by default, `removed` with `--prune-namespaces`,
`failed` with the reason)

3. **Surface competing copies.** When the report carries `frameworkCopies`, tell the user which
trees exist and at what versions — a drift notice fires once per tree, so two contradictory
notices mean two installs, not a framework bug. `~/.ai-badger/framework` is ai-badger's own
fallback clone and nothing updates it in place; offer to re-run with `--prune-cache` to
remove it. **Never offer to delete `~/.claude/plugins/cache/`** — Claude Code owns that path
and ai-badger only reads it.

3b. **Offer the prune candidates — never prune them.** `skillUsage.unused` names skills this
project holds and nobody invoked over `skillUsage.window`. The payoff is the listing budget:
a host allots a fixed slice of context to skill descriptions and drops the least-invoked ones
first, so an unused skill crowds one somebody does use. Tell the user the candidates and how
to decline them — `exclude.skills` in `config.json`, which is self-executing on the next
refresh (`drift.configChanged`) — and stop there. **`config.json` is project-owned; never
edit it as part of a refresh.**

Report the rest of the section with the candidates, not instead of them:
- `used` carries `evidence` — `invocation` (someone ran it) or `hook` (nobody ran it, but a
hook it ships fired, so it is doing work every session). Both mean leave it alone
- `cannotTell` is the honest bucket, and it is not a weaker `unused`: a skill listed there
was never observable. Never propose pruning one
- `window.days` bounds every claim. A short window and a quarterly skill produce a
confident-sounding recommendation that is simply wrong — say the number out loud
- `limits` states what the channels cannot see. Repeat it; a recommendation without it is
the one the user will regret
- `hint`, when present, replaces the recommendation: nothing could be observed, and the fix
it names (`behaviorist.py on 4h`, then work normally) is the whole answer

3c. **Present the orphaned namespaces and ask.** When the report carries `hermesNamespaces`,
list each `path` with its `links` count and the `target` that no longer exists, then **ask
the user whether to remove them**. Only on a yes, re-run the command with
`--prune-namespaces`. Never pass the flag on your own initiative — a namespace can dangle
because its project sits on a drive that is not mounted right now, and a refresh that
deletes it takes the user's Hermes skill wiring with it. Two things to say out loud:
- the sweep covers **every** project's namespace, not just this one. That is deliberate —
an orphan's project no longer exists to run `den-refresh` in, so nothing else will ever
reach it — but it means the paths named may belong to work the user has forgotten
- only the links ai-badger placed are removed. Anything else in that directory — a
Hermes-authored skill, a link pointing outside a `.ai-badger/skills/` tree — stays, and
the directory stays with it: that is what a non-zero `kept` means. A directory holding
no ai-badger link at all, such as a Hermes category like `react` or `uncategorized`, is
never listed and never touched. If the user expected one of those gone, it is theirs to
delete by hand

4. **Review the diff.** After re-scaffold, `git diff` shows exactly what
changed. Seed-once files (state.json, markers-context.json, model.json) are
preserved and won't appear in the diff unless they were mutated by the
project before the refresh.

5. **Commit or discard.** Managed files should be committed to pick up the
framework updates. Seed-once files are project-owned and never overwritten.

## How it differs from `welcome-ai-badger`

| | welcome-ai-badger | den-refresh |
|---|---|---|
| When to use | First time setup | Subsequent updates |
| Detection | Runs detect.py | Reads existing config |
| Config | Agent authors new config.json | Uses existing config.json |
| Questions | Asks for summary, domain, persona routing, plugin scope | No questions |
| Plugin install | Runs plugin install commands | Skips plugin install |
| Skills | Scaffolds from the skill list | Extracts skill names from manifest |

## Rules

- **Never re-detect.** den-refresh uses the project's existing config.json as-is.
If the config needs updating (new stacks, changed commands), edit it first,
then run den-refresh. **Exception:** den-refresh detects stacks that have signals
in the target but are missing from config, and reports them as `newStacks` —
advisory only, it never gates the re-scaffold (#134). Two paths from there, both
project-owned: **accept** — add the stack to `config.stacks` and re-run; the edit
itself is drift (`configChanged`, #128), so the re-scaffold that delivers it is
self-executing. **Decline** — add it to `.ai-badger/stack-ignore.json`; never
overwritten by a re-scaffold.
- **Seed-once files survive.** `state.json`, `markers-context.json`, and
`model.json` are seed-once and preserved across re-scaffolds (Why — see Gotchas.).
- **Preserved regions survive.** Managed agent files (`CLAUDE.md`,
`.ai-badger/CLAUDE.md`, `AGENTS.md`, the Copilot and Hermes files) are
regenerated in full, so project-authored content in them is dropped *unless*
it sits between `` and ``.
When a refresh reports dropped content, that is the fix to offer (Why — see Gotchas.).
- **Stack ignore list.** If `.ai-badger/stack-ignore.json` exists, stacks
listed in its `ignore` array are excluded from `newStacks` detection.
Use this to suppress false-positive stack detection (e.g. `python`
detected because `.mcp.json` references `python3` for a tool dependency).
The file is project-owned (manual) and never overwritten by re-scaffold.
- **Skills with extensions are refreshed.** The script extracts skill names
from the manifest, so skills like `task` (with `github`/`hermes` extensions)
are re-scaffolded and their extensions re-embedded.
- **Managed files are overwritten.** Everything else under `.ai-badger/` that
the framework originally placed is refreshed to the framework's current
content. Review the diff before committing.
- **Usage evidence has two sources and one of them cannot prove absence.** The invocation
channel reads Claude Code's own transcript store (`~/.claude/projects/<mangled cwd>/*.jsonl`,
this project's sessions and its worktrees) for `Skill` calls and slash commands — any skill,
but only on that host, and only as far back as Claude Code retains transcripts. The hook
channel reads call-behaviorist's audit log, which records hooks, so it can confirm a skill is
working and never that one is idle. Only the invocation channel produces a prune candidate;
with no transcript store, every skill lands in `cannotTell` and the report recommends nothing.
Neither channel reads message content — skill names and timestamps only.
- **Only `~/.ai-badger/framework` is ever pruned, and only on request.** ai-badger created
that clone, so it may remove it — never silently, only under `--prune-cache`, never when it
is the root in use, and never when the path is a symlink or holds one that leaves it. Every
other tree (Claude Code's plugin cache, a framework checkout) is reported and left alone: no
command destroys state it did not create.

## Gotchas

- **Seed-once files survive.** `state.json`, `markers-context.json` and `model.json` are
preserved across re-scaffolds — a refresh never resets them.
- **Preserved regions are the only survival path.** Managed agent files are regenerated in
full; project-authored content in them is dropped unless it sits between
`` and ``.
- **Absence is not a declaration.** A deleted skill, persona, invariant or instruction comes
back on the next refresh — add its name to `exclude` in `config.json` to decline it for good.

## Notes

- If the project's config.json is invalid, den-refresh exits with an error.
Fix the config first (re-run `welcome-ai-badger` steps 2-4 if needed), then
run den-refresh.
- If `index.json` is missing or stale in the framework checkout, run
`python3 "$AI_BADGER/tooling/index_build.py"` first.
- den-refresh delegates to the same `scaffold.py` that `welcome-ai-badger`
uses — the re-scaffold is identical to an initial scaffold, just driven by
an existing config.
- A deleted skill, persona, invariant or instruction comes back: absence is not a
declaration (Why — see Gotchas.). To decline one for good, add its name to `exclude` in `config.json`
(`{"skills": ["mcp-index"]}`) and re-run den-refresh — the edit is self-executing
(`drift.configChanged`, #128), so no separate step is needed. The refresh then stops
delivering it and removes the discovery symlinks ai-badger placed for it. The same applies
to any other config-only edit: `commands`, `personaRouting`, `agents`, `stacks`.
- **Dropping a stack from `config.stacks` is the other way to stop asking**, and it now
converges the same way: the entries that stack delivered are reported as `drift.orphaned` and
pruned by the re-scaffold. Before 0.42.0 the removal was invisible and the files were left
behind (#116).

## Error Recovery

When `refresh.py` exits non-zero or returns JSON with an `error` field, attempt
recovery before surfacing the failure to the user.

1. **Parse the error.** The script emits structured JSON — read the `error` field
and any `validationErrors` array to classify the failure.

2. **Attempt automatic recovery.** Try the applicable fix, then re-run the
refresh command from step 1 of the Flow.

> Fix table: read references/error-recovery.md when refresh.py exits non-zero or returns a JSON `error` field.

After applying a fix, **re-run the refresh**. If it succeeds, report what was
fixed and continue with the normal flow (review diff, commit).

3. **Recovery failed — offer to create a GitHub issue.** Follow
`.ai-badger/skills/welcome-ai-badger/references/reporting-a-framework-bug.md` **when a fix
does not recover the failure**: ask
permission first, gate on `gh` being installed and authenticated, sanitize the config
before including it. **Never create the issue without explicit user approval** — that rule
holds even if the reference file is not present.

## Verification Checklist

- [ ] `refresh.py` exited 0
- [ ] Report read section by section: `frameworkVersion`, `drift.*`, `reScaffolded`, `note`, `frameworkCopies`, `hermesNamespaces`
- [ ] Competing copies surfaced; `~/.ai-badger/framework` pruned only on request
- [ ] Orphaned Hermes namespaces presented and the user asked; `--prune-namespaces` passed only on a yes
- [ ] Prune candidates offered, never pruned — `config.json` untouched
- [ ] Diff reviewed before commit
- [ ] Seed-once files (`state.json`, `markers-context.json`, `model.json`) absent from the diff
## Shared child recovery

An enrolled shared child uses its private `.ai-badger/shared-scope.json` authored settings.
Ordinary refresh refuses before changing it and prints a concrete `shared_scope.py sync`
command. Run that command with the child's parent `.ai-badger` as `--source`. Sync renders
only this child with its original local stacks, merges current parent defaults with its
authored overrides, and preserves private identity and state. Review the child diff and
verify its instruction and skill discovery after sync.