/resonance-ops-update-resonance: upgrade the framework, preserve the project
Role: the Maintainer.
Invoked as: /update-resonance.
Input: target project, desired Resonance version or source checkout.
Output: upgraded Resonance framework files, verified against the target project.
Definition of Done: managed framework files are upgraded, project memory and application code are untouched, the recovery journal is complete, validation passes, and the operator can see exactly what changed.
You are upgrading a public framework inside a real project. Treat the project as the source of truth. Do not force a bulk replacement over a dirty or customized workspace.
Prerequisites (fail fast)
Source Resolution
A target project does not need to record the Resonance upstream URL. Most upgraded projects will only have .agents/ and local memory. Resolve the source in this order:
- Explicit source from the user: local path, Git URL, branch, tag, or commit.
- Local trusted checkout: a user-provided or configured Resonance source path, if it exists and its version matches the requested upgrade.
- Installed package metadata: if the target contains a framework manifest with repository and version fields, use it as a hint, then verify it against the fetched source.
- Official public source: fetch
https://github.com/manusco/resonance.git with gh repo clone manusco/resonance or git clone https://github.com/manusco/resonance.git into a temp directory outside the target project.
- Blocked: if no source can be fetched or read, stop before edits and report the exact command or path needed.
Verification:
- The resolved source must contain
.agents/skills/, .forge/ for source-mode validation, resonance.sh, resonance.ps1, and package.json.
- The source version must match the requested version, unless the user explicitly asked for a branch or commit.
- The temp clone or staging directory must not be inside the target project.
- Never infer the source URL from the target application remote. The app's
origin is the product repo, not the framework source.
Ownership Boundary
Managed by the framework
These may be upgraded when preflight says they are safe:
.agents/skills/
.forge/
.claude/skills/
.cursor/skills/
.opencode/commands/
resonance.sh
resonance.ps1
- generated bridge files when the target has no local edits to them
Project-owned
Never overwrite these as part of a framework upgrade:
.resonance/00_soul.md
.resonance/01_state.md
.resonance/02_memory.md
.resonance/ledger/
.resonance/memory/
- application code
- project docs, plans, audits, handovers, and tests
- private or company skills under
.agents/skills/ that are absent from the framework ownership manifest
.resonance/project-skills.lock.json, the committed content lock for those project skills
- project-specific
AGENTS*.md, CLAUDE*.md, or host settings unless the diff proves they are generated framework bridges with no local edits
Project-owned documentation is never runtime authority for framework validation. Forge derives command targets and runtime skill metadata from framework-owned skill templates. In explicit consumer mode, Forge never reads or writes root project documentation. An existing unowned README.md, AGENTS.md, CLAUDE.md, or host bridge is preserved byte-for-byte and excluded from framework ownership. Generated files such as docs/skill-manifest.json may be stale or absent without blocking an upgrade. A preserved instruction bridge is reported as an integration note, not an installation failure.
Legacy exception: if .resonance/learnings.jsonl exists and the user approves the migration, append its lessons into .resonance/02_memory.md and remove the legacy file only after the append is verified.
Optional update notice
The release notice is explicit opt-in with python3 resonance_update.py notice enable. Its setting lives in the operating system's user configuration directory, outside project repositories. It checks stable releases with tight timeout and size bounds, stores no project path, project data, credentials, or release prose, and failure never blocks a launcher. A notice only reports availability. It never applies an update. Apply remains a separate reviewed transaction bound to the exact version, full source commit, and plan digest.
Algorithm
Copy this checklist and tick items as you go.
- Read the project: Inspect
git status --short, existing Resonance directories, and the target's AGENTS.md / CLAUDE.md shape. -> verify: local changes are grouped as framework-managed, project-owned, or unrelated.
- Resolve source: Use the Source Resolution order. Fetch or verify the source outside the target project. -> verify: source path, version, and fetch method are named.
- Plan the complete installation: Run the pinned checkout's
resonance_update.py --source <source> --target <target> --version <version> --summary. Omit --profile; new manifests use the complete source profile. --profile source and --profile compiled remain accepted aliases. Use --json when a tool needs the complete plan. For an installation without a manifest, first verify a checkout of its installed release, then use the new updater with --source <old-release> --target <target> --adopt; adoption changes only the ownership manifest and claims only byte-identical released files. For old manifests, use recorded hashes or verified installed release provenance to establish ownership. Unproven existing bytes in newly included paths remain untouched and are reported as conflicts. Review the source revision, plan digest, path reasons, and recovery policy. -> verify: adoption changes only the ownership manifest; the dry run changes nothing.
- Block unsafe states: Stop if any touched path has an unresolved conflict, unknown ownership, or local customization that cannot be classified. A live file may be reconciled when it matches the selected source, the recorded ownership hash, or the verified installed release commit or exact local version tag. Never use the consumer's clean Git status as ownership proof. -> verify: each blocker names the path and missing evidence; application files outside the complete managed path set cannot enter the write set.
- Prepare recovery before edits: For each touched existing path, use the target repository's pinned
HEAD blob only when raw bytes and executable mode match; copy only preimages Git cannot recover into .resonance/updates/<id>/files/. -> verify: the receipt lists every touched path and its recovery source; Git-only transactions create no .resonance/backups/ directory.
- Stage the new framework aside: Copy the complete framework into a temporary staging directory inside
.resonance/tmp/ or system temp, never directly over live files. -> verify: staged paths match the complete managed path set, including .forge.
- Compare and classify: Compare staged framework files against live managed paths. Preserve target-local files that are outside generated trees. Replacement is allowed only after the recovery receipt and fallback copies are complete. -> verify: no project-owned path appears in the write set.
- Apply transactionally: Run the same updater command with
--apply --revision <reviewed-full-commit> --plan-digest <reviewed-plan-digest>. It refuses a changed source or plan, stages and verifies every incoming file, writes by path, records source revision and ownership hashes, then validates. -> verify: each write target resolves inside the project root and the recovery journal says complete.
- Migrate legacy memory only with proof: If approved, append legacy lessons, verify they appear in
.resonance/02_memory.md, then remove learnings.jsonl. -> verify: no lesson is lost.
- Validate the complete installation: Run
python3 .forge/consumer_check.py --root .; do not run .forge/tests/run.py, which tests the Resonance source repository and its public scaffold. Then run /system-health and any project-specific smoke check that does not require unrelated dirty files to be resolved. -> verify: the consumer check reports ok: true, and failures are reported with exact commands and output. A locally unavailable PowerShell runtime is informational because release CI parses resonance.ps1 on Windows.
- Verify project skills: When
.resonance/project-skills.lock.json exists, run python3 <target>/.forge/project_skills.py --check --root <target>. Never regenerate the project-owned lock as an implicit part of a framework upgrade. -> verify: every committed private skill still matches its pre-upgrade content lock.
- Report: Summarize changed paths, preserved project-owned paths, recovery journal, fallback-copy count, validation output, and rollback instructions. For no-op plans report that no files or recovery data changed.
Recovery
- Source cannot be resolved or fetched -> stop before edits. Name the missing source path, network access, or clone command.
- Preflight finds unresolved conflicts in touched paths -> stop. Do not edit.
- Preflight finds unrelated dirty application files -> proceed only if the write set excludes them and report that they were left alone.
- Journal pinning or fallback-copy creation fails -> stop before managed edits.
- Staging validation fails -> remove staging directory and stop before target files change.
- Apply or post-update validation fails -> the updater attempts to restore touched paths from the pinned Git commit and listed fallback copies. If automatic rollback succeeds, report both the failure and restored state. If rollback also fails, preserve both errors and the exact recovery journal path.
- A completed update needs later reversal -> use
resonance_update.py --rollback <transaction-directory>. Do not claim success before validation passes.
.agents/skills is empty after apply -> restore from the recovery journal immediately. Empty skills disable the framework.
- Project-specific
AGENTS.md differs from framework AGENTS.md -> do not overwrite silently. Either preserve it and add missing bridge guidance manually, or ask for approval with a diff.
Out of Scope
- Modifying application code.
- Resolving unrelated merge conflicts.
- Rewriting project memory or soul files.
- Deleting local customizations because the framework source lacks them.
Cognitive Frameworks
The Safe Upgrade Path
An upgrade is a migration, not a bulk copy. The work is plan, provenance check, staged copy, recoverable apply, validation, and rollback. If any part is not verifiable, stop before touching files.
Generated vs. Owned
Generated framework trees can be replaced after the receipt records recoverable preimages because stale files are dangerous. Project-owned files must be merged or left alone because overwriting them loses context.
Reference Library
Operating Standard
Apply the Resonance operating standard from AGENTS.md (always loaded): the builder Voice and its banned-word list (no AI slop, no em dashes), Recommendation-First decisions (models recommend, the user decides), the Completion protocol (end with DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT, backed by evidence, escalate after 3 failed tries), and the Ratchet (record durable learnings in the project memory; when .resonance/ledger/ exists it is the system of record for decisions, lessons, metrics, customers, and experiments, while 02_memory.md keeps [lib] notes and pointers).
Execution note: Use the host's native file, search, shell, browser, and delegation tools. Follow the procedure and verify material claims with evidence. Keep internal reasoning private and report decisions, actions, and results clearly.
1---2name: resonance-ops-update-resonance3description: The Maintainer. Upgrades the Resonance framework kernel with a preflight plan, scoped replacement, recoverable transaction, rollback path, and verification. Use when migrating a project to a new version of Resonance.4archetype: procedure5metadata:6 source: https://skillmd.com/skills/manusco/resonance-ops-update-resonance7---89# /resonance-ops-update-resonance: upgrade the framework, preserve the project1011> **Role:** the Maintainer.12> **Invoked as:** `/update-resonance`.13> **Input:** target project, desired Resonance version or source checkout.14> **Output:** upgraded Resonance framework files, verified against the target project.15> **Definition of Done:** managed framework files are upgraded, project memory and application code are untouched, the recovery journal is complete, validation passes, and the operator can see exactly what changed.1617You are upgrading a public framework inside a real project. Treat the project as the source of truth. Do not force a bulk replacement over a dirty or customized workspace.1819## Prerequisites (fail fast)2021- [ ] Source version is resolved with the Source Resolution order below.22- [ ] Target project root is confirmed.23- [ ] Git status has been classified by path.24- [ ] No unresolved conflicts exist in any path the upgrade would touch.25- [ ] The target can write a recovery journal and any required per-path fallback copies.26- [ ] The target's ownership history is understood. New and profile-missing installs use the complete `source` profile by default; old `source` and `compiled` arguments are compatibility aliases. Existing manifests retain their recorded profile only to prove historical ownership.2728## Source Resolution2930A target project does not need to record the Resonance upstream URL. Most upgraded projects will only have `.agents/` and local memory. Resolve the source in this order:31321. **Explicit source from the user**: local path, Git URL, branch, tag, or commit.332. **Local trusted checkout**: a user-provided or configured Resonance source path, if it exists and its version matches the requested upgrade.343. **Installed package metadata**: if the target contains a framework manifest with repository and version fields, use it as a hint, then verify it against the fetched source.354. **Official public source**: fetch `https://github.com/manusco/resonance.git` with `gh repo clone manusco/resonance` or `git clone https://github.com/manusco/resonance.git` into a temp directory outside the target project.365. **Blocked**: if no source can be fetched or read, stop before edits and report the exact command or path needed.3738Verification:3940- The resolved source must contain `.agents/skills/`, `.forge/` for source-mode validation, `resonance.sh`, `resonance.ps1`, and `package.json`.41- The source version must match the requested version, unless the user explicitly asked for a branch or commit.42- The temp clone or staging directory must not be inside the target project.43- Never infer the source URL from the target application remote. The app's `origin` is the product repo, not the framework source.44## Ownership Boundary4546### Managed by the framework4748These may be upgraded when preflight says they are safe:4950- `.agents/skills/`51- `.forge/`52- `.claude/skills/`53- `.cursor/skills/`54- `.opencode/commands/`55- `resonance.sh`56- `resonance.ps1`57- generated bridge files when the target has no local edits to them5859### Project-owned6061Never overwrite these as part of a framework upgrade:6263- `.resonance/00_soul.md`64- `.resonance/01_state.md`65- `.resonance/02_memory.md`66- `.resonance/ledger/`67- `.resonance/memory/`68- application code69- project docs, plans, audits, handovers, and tests70- private or company skills under `.agents/skills/` that are absent from the framework ownership manifest71- `.resonance/project-skills.lock.json`, the committed content lock for those project skills72- project-specific `AGENTS*.md`, `CLAUDE*.md`, or host settings unless the diff proves they are generated framework bridges with no local edits7374Project-owned documentation is never runtime authority for framework validation. Forge derives command targets and runtime skill metadata from framework-owned skill templates. In explicit consumer mode, Forge never reads or writes root project documentation. An existing unowned `README.md`, `AGENTS.md`, `CLAUDE.md`, or host bridge is preserved byte-for-byte and excluded from framework ownership. Generated files such as `docs/skill-manifest.json` may be stale or absent without blocking an upgrade. A preserved instruction bridge is reported as an integration note, not an installation failure.7576Legacy exception: if `.resonance/learnings.jsonl` exists and the user approves the migration, append its lessons into `.resonance/02_memory.md` and remove the legacy file only after the append is verified.7778### Optional update notice7980The release notice is explicit opt-in with `python3 resonance_update.py notice enable`. Its setting lives in the operating system's user configuration directory, outside project repositories. It checks stable releases with tight timeout and size bounds, stores no project path, project data, credentials, or release prose, and failure never blocks a launcher. A notice only reports availability. It never applies an update. Apply remains a separate reviewed transaction bound to the exact version, full source commit, and plan digest.8182## Algorithm8384Copy this checklist and tick items as you go.85860. **Read the project**: Inspect `git status --short`, existing Resonance directories, and the target's `AGENTS.md` / `CLAUDE.md` shape. -> verify: local changes are grouped as framework-managed, project-owned, or unrelated.871. **Resolve source**: Use the Source Resolution order. Fetch or verify the source outside the target project. -> verify: source path, version, and fetch method are named.882. **Plan the complete installation**: Run the pinned checkout's `resonance_update.py --source <source> --target <target> --version <version> --summary`. Omit `--profile`; new manifests use the complete `source` profile. `--profile source` and `--profile compiled` remain accepted aliases. Use `--json` when a tool needs the complete plan. For an installation without a manifest, first verify a checkout of its installed release, then use the new updater with `--source <old-release> --target <target> --adopt`; adoption changes only the ownership manifest and claims only byte-identical released files. For old manifests, use recorded hashes or verified installed release provenance to establish ownership. Unproven existing bytes in newly included paths remain untouched and are reported as conflicts. Review the source revision, plan digest, path reasons, and recovery policy. -> verify: adoption changes only the ownership manifest; the dry run changes nothing.893. **Block unsafe states**: Stop if any touched path has an unresolved conflict, unknown ownership, or local customization that cannot be classified. A live file may be reconciled when it matches the selected source, the recorded ownership hash, or the verified installed release commit or exact local version tag. Never use the consumer's clean Git status as ownership proof. -> verify: each blocker names the path and missing evidence; application files outside the complete managed path set cannot enter the write set.904. **Prepare recovery before edits**: For each touched existing path, use the target repository's pinned `HEAD` blob only when raw bytes and executable mode match; copy only preimages Git cannot recover into `.resonance/updates/<id>/files/`. -> verify: the receipt lists every touched path and its recovery source; Git-only transactions create no `.resonance/backups/` directory.915. **Stage the new framework aside**: Copy the complete framework into a temporary staging directory inside `.resonance/tmp/` or system temp, never directly over live files. -> verify: staged paths match the complete managed path set, including `.forge`.926. **Compare and classify**: Compare staged framework files against live managed paths. Preserve target-local files that are outside generated trees. Replacement is allowed only after the recovery receipt and fallback copies are complete. -> verify: no project-owned path appears in the write set.937. **Apply transactionally**: Run the same updater command with `--apply --revision <reviewed-full-commit> --plan-digest <reviewed-plan-digest>`. It refuses a changed source or plan, stages and verifies every incoming file, writes by path, records source revision and ownership hashes, then validates. -> verify: each write target resolves inside the project root and the recovery journal says `complete`.948. **Migrate legacy memory only with proof**: If approved, append legacy lessons, verify they appear in `.resonance/02_memory.md`, then remove `learnings.jsonl`. -> verify: no lesson is lost.959. **Validate the complete installation**: Run `python3 .forge/consumer_check.py --root .`; do not run `.forge/tests/run.py`, which tests the Resonance source repository and its public scaffold. Then run `/system-health` and any project-specific smoke check that does not require unrelated dirty files to be resolved. -> verify: the consumer check reports `ok: true`, and failures are reported with exact commands and output. A locally unavailable PowerShell runtime is informational because release CI parses `resonance.ps1` on Windows.9610. **Verify project skills**: When `.resonance/project-skills.lock.json` exists, run `python3 <target>/.forge/project_skills.py --check --root <target>`. Never regenerate the project-owned lock as an implicit part of a framework upgrade. -> verify: every committed private skill still matches its pre-upgrade content lock.9711. **Report**: Summarize changed paths, preserved project-owned paths, recovery journal, fallback-copy count, validation output, and rollback instructions. For no-op plans report that no files or recovery data changed.9899## Recovery100101- Source cannot be resolved or fetched -> stop before edits. Name the missing source path, network access, or clone command.102- Preflight finds unresolved conflicts in touched paths -> stop. Do not edit.103- Preflight finds unrelated dirty application files -> proceed only if the write set excludes them and report that they were left alone.104- Journal pinning or fallback-copy creation fails -> stop before managed edits.105- Staging validation fails -> remove staging directory and stop before target files change.106- Apply or post-update validation fails -> the updater attempts to restore touched paths from the pinned Git commit and listed fallback copies. If automatic rollback succeeds, report both the failure and restored state. If rollback also fails, preserve both errors and the exact recovery journal path.107- A completed update needs later reversal -> use `resonance_update.py --rollback <transaction-directory>`. Do not claim success before validation passes.108- `.agents/skills` is empty after apply -> restore from the recovery journal immediately. Empty skills disable the framework.109- Project-specific `AGENTS.md` differs from framework `AGENTS.md` -> do not overwrite silently. Either preserve it and add missing bridge guidance manually, or ask for approval with a diff.110111## Out of Scope112113- Modifying application code.114- Resolving unrelated merge conflicts.115- Rewriting project memory or soul files.116- Deleting local customizations because the framework source lacks them.117118## Cognitive Frameworks119120### The Safe Upgrade Path121122An upgrade is a migration, not a bulk copy. The work is plan, provenance check, staged copy, recoverable apply, validation, and rollback. If any part is not verifiable, stop before touching files.123124### Generated vs. Owned125126Generated framework trees can be replaced after the receipt records recoverable preimages because stale files are dangerous. Project-owned files must be merged or left alone because overwriting them loses context.127128## Reference Library129130- **[Completion Attestation](../core/references/completion_attestation.md)**: Required sign-off format.131132## Operating Standard133134Apply the Resonance operating standard from AGENTS.md (always loaded): the builder Voice and its banned-word list (no AI slop, no em dashes), Recommendation-First decisions (models recommend, the user decides), the Completion protocol (end with DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT, backed by evidence, escalate after 3 failed tries), and the Ratchet (record durable learnings in the project memory; when `.resonance/ledger/` exists it is the system of record for decisions, lessons, metrics, customers, and experiments, while `02_memory.md` keeps `[lib]` notes and pointers).135136> **Execution note:** Use the host's native file, search, shell, browser, and delegation tools. Follow the procedure and verify material claims with evidence. Keep internal reasoning private and report decisions, actions, and results clearly.