Context
- Framework version: 1.6.255
- Project: 999-Agentic-Engineering-Framework (self-hosting mode)
- Reported: 2026-06-07T11:50:25Z
Description
Symptom
fw update --help advertises --rollback Restore previous version as a general option (lib/update.sh:30). The help text describes two code paths — vendored (lib/update.sh:73, 4-step) and global git-based (lib/update.sh:223, 3-step) — but only the vendored path implements rollback.
Evidence
- Vendored rollback IS implemented: lib/update.sh:171-185 saves
$project_root/.agentic-framework.rollback/ via cp -r before re-vendor; lib/update.sh:18-21 wires --rollback → _do_rollback.
- Global path has NO rollback path. After
git -C $FRAMEWORK_ROOT reset --hard (lib/update.sh:_do_update_git), the prior state is unreachable from fw update --rollback — _do_rollback operates on the vendored backup dir.
- The help text claims rollback unconditionally (line 30), creating an expectation the code does not honour for global installs.
Impact
An operator on a global install who runs fw update and wants to revert is told by --help that --rollback exists, but the verb either errors (no backup dir) or silently does nothing useful. This is the kind of dispatch-surface asymmetry the T-2078 V1 ladder was hardening against.
Fix shapes (operator's call)
- Implement git-path rollback: tag a marker ref before
git reset --hard; _do_rollback resets back to it for git-mode installs.
- Document the limit: change help text to
--rollback Restore previous version (vendored installs only).
- Refuse
--rollback on global with a clear diagnostic pointing at git reflog as the manual recovery path.
Origin
Surfaced by the T-2234 incorporation inception of a consumer-update dispatch exercise; the dispatch template's STEP 6 rollback advice would mislead operators on global installs without this fix. Decorrelated reviewer flagged it as a real defect (review Part 3, item 4), not a design question.
Reported via fw upstream report from field installation
Context
Description
Symptom
fw update --helpadvertises--rollback Restore previous versionas a general option (lib/update.sh:30). The help text describes two code paths — vendored (lib/update.sh:73, 4-step) and global git-based (lib/update.sh:223, 3-step) — but only the vendored path implements rollback.Evidence
$project_root/.agentic-framework.rollback/viacp -rbefore re-vendor; lib/update.sh:18-21 wires--rollback→_do_rollback.git -C $FRAMEWORK_ROOT reset --hard(lib/update.sh:_do_update_git), the prior state is unreachable fromfw update --rollback—_do_rollbackoperates on the vendored backup dir.Impact
An operator on a global install who runs
fw updateand wants to revert is told by--helpthat--rollbackexists, but the verb either errors (no backup dir) or silently does nothing useful. This is the kind of dispatch-surface asymmetry the T-2078 V1 ladder was hardening against.Fix shapes (operator's call)
git reset --hard;_do_rollbackresets back to it for git-mode installs.--rollback Restore previous version (vendored installs only).--rollbackon global with a clear diagnostic pointing atgit reflogas the manual recovery path.Origin
Surfaced by the T-2234 incorporation inception of a consumer-update dispatch exercise; the dispatch template's STEP 6 rollback advice would mislead operators on global installs without this fix. Decorrelated reviewer flagged it as a real defect (review Part 3, item 4), not a design question.
Reported via
fw upstream reportfrom field installation