nobrainer-tech-flow 2.4.1 → 2.6.0

package/scripts/install.sh

@@ -4,7 +4,8 @@
 # Same flags, locations, conflict rule and setup record as scripts/install.py, so
 # either one can undo what the other did. Every run previews until --apply. The
 # skills are linked to this checkout (never copied), one managed instruction block
-# is added, and no standing authorization is ever granted. A managed block that is
+# is added. Its only standing authorization is the default daily update of Flow itself;
+# an existing block keeps notifying unless it already held that line. A managed block that is
 # already there is replaced by this version's text when it differs, and everything
 # outside the two markers stays byte for byte, as install.py does. One difference: a
 # block that carries options (a standing authorization, a wiki root or a preference)
@@ -19,7 +20,7 @@ unset CDPATH
 # The eighteen skills, and the names earlier layouts used. Tests keep these lists
 # equal to the ones in scripts/install_skills.py.
 SKILLS='nobrainer-auto-fine-tune nobrainer-autoimprove nobrainer-browser nobrainer-build
-nobrainer-codex-context nobrainer-decide nobrainer-dispatcher nobrainer-rca
+nobrainer-context nobrainer-decide nobrainer-dispatcher nobrainer-rca
 nobrainer-research nobrainer-review nobrainer-security nobrainer-sessions
 nobrainer-skill-doctor nobrainer-spec-driven-development nobrainer-team
 nobrainer-tech-flow nobrainer-wiki nobrainer-writing'
@@ -28,13 +29,13 @@ deep-audit deep-autoresearch deep-autoreview deep-bugs-finder deep-code-review
 deep-decide deep-rca dispatching-parallel-agents engineering-standards
 karpathy-auto-improver karpathy-llm-wiki llm-wiki nb-add nb-dispatcher nb-flow nb-get
 nb-multi nb-tidy nb-workflow nb-write nobrainer-autopilot nobrainer-capture-lesson
-nobrainer-continuous-improvement nobrainer-fast-audit nobrainer-human-like
+nobrainer-codex-context nobrainer-continuous-improvement nobrainer-fast-audit nobrainer-human-like
 nobrainer-memory nobrainer-memory-memsearch nobrainer-npm-secure nobrainer-reddit
 nobrainer-simplifier nobrainer-skill-browser nobrainer-starter nobrainer-style
 nobrainer-team-builder nobrainer-ultra nobrainer-ultracode-workflow nobrainer-wiki-add
 nobrainer-wiki-get nobrainer-wiki-tidy playwright-cli security-review session-handoff
 wiki-add wiki-get wiki-tidy'
-RETIRED='nobrainer-reddit'
+RETIRED='nobrainer-codex-context nobrainer-reddit'
 START='<!-- NOBRAINER-TECH-FLOW:START -->'
 END='<!-- NOBRAINER-TECH-FLOW:END -->'
 LEGACY_TEXT='(^|[^[:alnum:]_])nobrainer-ultra([^[:alnum:]_]|$)|^[[:space:]]*#{1,6}[[:space:]]+nobrainer([ .]?tech)?[[:space:]]+flow([^[:alnum:]_]|$)'
@@ -47,6 +48,12 @@ SEPARATORS=$(printf '\342\200[\250\251]')
 TAB=$(printf '\t')
 CR=$(printf '\r')
 
+# The update line of the block: on by default; an existing block that only notifies
+# (written with --no-auto-update, or the default before 2.6.0) keeps notifying.
+AUTO_UPDATE_LINE='- Once a day on first use, update nobrainer-tech-flow to its latest verified stable release from the canonical source, with a backup; change nothing else and ask if unsure.'
+NOTIFY_UPDATE_LINE='- Once a day on first use, tell the owner when a newer stable nobrainer-tech-flow release exists; do not update it yourself.'
+update_line=$AUTO_UPDATE_LINE
+
 # The block scripts/install_personalization.py writes without options, byte for byte
 # (a test compares them).
 block() {
@@ -61,7 +68,9 @@ block() {
 - Derive short-term goals from the user's long-term direction (LDD) and define observable completion criteria. At project start, inspect the existing structure and layers, then recommend a fitting approach.
 - At project start, discover whether a relevant wiki exists. If one exists, read its `WIKI.md`, locate relevant `index.md` entries with a targeted search, then read only the relevant pages. Ask before creating a wiki unless project rules or prior authorization already settle it.
 - Assess context and checkpoint at appropriate milestones. Recommend session rotation when it would help; do not restart or archive automatically. When rotation is authorized, use the supported lifecycle, verify exact successor takeover by ID/readback, and archive the old session only after that readback. Do not create recursive visible workers or claim a restart when unsupported.
-- On the first `nobrainer-tech-flow` use each calendar day, check for available updates when this client exposes a supported check and notify the owner; do not apply them automatically. If the client is inactive or cannot check, do not claim a check occurred.
+EOF
+	printf '%s\n' "$update_line"
+	cat <<'EOF'
 - Use `nobrainer-writing` for material writing when available; make technical documentation concrete, source-backed, and technically verified. Preserve facts, use the user's language, and verify at the actual delivery layer.
 <!-- NOBRAINER-TECH-FLOW:END -->
 EOF
@@ -285,6 +294,38 @@ is_our_link() {
 	[ "$_o_resolved" = "$2" ]
 }
 
+# Put a claimed entry ($1) back at its name ($2) unless something new stands there; the
+# private folder it was moved into goes too. A blocked restore keeps the claim and says where.
+unclaim() {
+	# Restore through the same native no-replace primitive as the Python installer.
+	# Normal shell installs need no Python; without it, a recovery claim stays intact.
+	if command -v python3 >/dev/null 2>&1 && python3 - "$root/scripts" "$1" "$2" <<'PYTHON'
+import sys
+from pathlib import Path
+sys.path.insert(0, sys.argv[1])
+from install_skills import restore_claim
+try:
+    restore_claim(Path(sys.argv[3]), Path(sys.argv[2]))
+except (OSError, RuntimeError) as exc:
+    print(exc, file=sys.stderr)
+    sys.exit(1)
+PYTHON
+	then
+		return 0
+	fi
+	err "PRESERVED: atomic restore unavailable or blocked; could not put $2 back; it is kept at $1"
+	return 1
+}
+
+# A recorded skill link this checkout made: $1 is the link, $2 the skill name. The link of
+# a retired module dangles, so it is compared as written.
+owns_link() {
+	case " $RETIRED " in
+		*" $2 "*) is_exact_legacy_link "$1" "$2" ;;
+		*) is_our_link "$1" "$root/skills/$2" ;;
+	esac
+}
+
 # Resolve links before "..", including dangling final links. A trailing slash
 # preserves a pathname's trailing newlines across command substitution.
 resolve_legacy_path() (
@@ -410,7 +451,8 @@ read_state() {
 					'  ]' | '  ],') _r_in= ;;
 					*)
 						json_field "\": ${_r_line#    }" || return 1
-						case " $(printf '%s' "$SKILLS" | tr '\n' ' ') " in *" $json_value "*) ;; *) return 1 ;; esac
+						# A record from an earlier release may hold a module since retired.
+						case " $(printf '%s' "$SKILLS $RETIRED" | tr '\n' ' ') " in *" $json_value "*) ;; *) return 1 ;; esac
 						case " $st_created " in *" $json_value "*) return 1 ;; esac
 						st_created="$st_created $json_value" ;;
 				esac
@@ -681,7 +723,7 @@ check_record() {
 }
 
 plan_skills() {
-	to_link= link_count=0 kept_count=0 problems=
+	to_link= link_count=0 kept_count=0 problems= to_retire=
 	for _p_name in $SKILLS; do
 		_p_source=$root/skills/$_p_name
 		[ -f "$_p_source/SKILL.md" ] || die 2 "this checkout is incomplete: $_p_source/SKILL.md is missing"
@@ -708,7 +750,13 @@ CONFLICT: $_p_name: $_p_source -> $_p_target"
 					if ! is_exact_legacy_link "$_p_target" "$_p_name"; then
 						err "PRESERVED_FOREIGN: $_p_name: retired from nobrainer-tech-flow; left unchanged: $_p_target"
 						continue
-					fi ;;
+					fi
+					# This setup's record lists the link, as an undo would remove it.
+					case " $st_created " in
+						*" $_p_name "*)
+							to_retire="$to_retire $_p_name"
+							continue ;;
+					esac ;;
 			esac
 			problems="$problems
 LEGACY: $_p_name: $_p_target"
@@ -767,6 +815,12 @@ plan_instructions() {
 		die 3 "malformed or duplicated nobrainer-tech-flow managed markers in $target"
 	fi
 	file_status=present
+	# An existing block keeps updating only when it holds the update line as its own line;
+	# a notify-only, edited or unknown line keeps notifying, so no grant is ever inferred.
+	if block_lines "$target" && ! head -n "$block_to" "$target" | tail -n "+$block_from" |
+		LC_ALL=C sed 's/[[:space:]]*$//' | grep -a -q -x -F -e "$AUTO_UPDATE_LINE"; then
+		update_line=$NOTIFY_UPDATE_LINE
+	fi
 	# A block of an earlier version is brought up to date, but only one that can be replaced
 	# without losing anything: its markers stand on lines of their own, and it holds no option.
 	if ! block_is_default && block_lines "$target" && ! block_has_options; then
@@ -788,6 +842,10 @@ block_lines() {
 	[ "$block_from" -lt "$block_to" ]
 }
 
+update_status() {
+	if [ "$update_line" = "$NOTIFY_UPDATE_LINE" ]; then echo CHECK_AND_NOTIFY; else echo AUTHORIZED_SAFE_VERIFIED_ONLY; fi
+}
+
 block_is_default() {
 	block_lines "$target" || return 1
 	_b_text=$(head -n "$block_to" "$target" | tail -n "+$block_from")
@@ -797,7 +855,7 @@ block_is_default() {
 }
 
 # block_has_options: the block block_lines found in $target carries something the owner
-# chose: a standing authorization, a wiki root or a preference. Only install.py and
+# chose: a pre-2.6 standing authorization, a wiki root or a preference. Only install.py and
 # scripts/install_personalization.py --keep-options carry those over to a new block.
 block_has_options() {
 	head -n "$block_to" "$target" | tail -n "+$block_from" |
@@ -819,6 +877,9 @@ variable_note() {
 preview() {
 	say "$source_line for $label"
 	say "SKILLS: $link_count to link into $skills_dir ($kept_count already linked)"
+	for _v_name in $to_retire; do
+		say "REMOVE_RETIRED: $_v_name: made by this setup, now renamed: $skills_dir/$_v_name"
+	done
 	if [ "$inherit" = 1 ]; then
 		say "INHERITS_CODEX: $target imports $codex_file; no duplicate block added"
 	else
@@ -831,7 +892,7 @@ preview() {
 		elif [ "$file_status" = refresh ]; then
 			block_lines "$target"
 			say "UPDATE: nobrainer-tech-flow personalization block"
-			say "AUTO_UPDATE: CHECK_AND_NOTIFY"
+			say "AUTO_UPDATE: $(update_status)"
 			say "AUTO_SESSION_RESTART: ASSESS_CHECKPOINT_RECOMMEND"
 			say "PRESERVED: content outside the managed block"
 			say "DIFF:"
@@ -839,7 +900,7 @@ preview() {
 			block | sed 's/^/+/'
 		else
 			say "MISSING: nobrainer-tech-flow personalization block"
-			say "AUTO_UPDATE: CHECK_AND_NOTIFY"
+			say "AUTO_UPDATE: $(update_status)"
 			say "AUTO_SESSION_RESTART: ASSESS_CHECKPOINT_RECOMMEND"
 			say "DIFF:"
 			block | sed 's/^/+/'
@@ -914,6 +975,10 @@ write_instructions() {
 }
 
 install() {
+	# plan_skills needs the retired links the record lists; check_record judges the record
+	# after the skills, as before, so a record that cannot be read only lists none here.
+	st_created=
+	if [ -f "$state" ] && [ ! -L "$state" ]; then read_state "$state" || st_created=; fi
 	plan_skills
 	plan_instructions
 	check_record
@@ -986,8 +1051,43 @@ install() {
 	elif [ "$wrote" = 1 ]; then
 		new_target=$target new_backup=$made_backup new_hash=$(sha256 "$target")
 	fi
-	if [ -n "$created" ] || [ "$wrote" = 1 ] || { [ "$record" = 1 ] && [ "$new_hash" != "$st_hash" ]; }; then
-		new_created=$(printf '%s\n' $st_created $created | LC_ALL=C sort -u | tr '\n' ' ')
+	# The retired links the record lists go last, after every other write. Each is moved into
+	# a private folder and checked there; one that changed after the check goes back as it is.
+	# They come back if the record cannot be saved, and are deleted only once it is.
+	retired_claims= retirement_error= retirement_restore_error=
+	for _a_name in $to_retire; do
+		_a_link=$skills_dir/$_a_name
+		is_exact_legacy_link "$_a_link" "$_a_name" || continue
+		_a_text=$(readlink "$_a_link") || continue
+		if ! _a_claim=$(mktemp -d "$skills_dir/.nobrainer-retire-XXXXXX"); then
+			retirement_error=1
+			break
+		fi
+		if ! mv "$_a_link" "$_a_claim/$_a_name" 2>/dev/null; then
+			rmdir "$_a_claim"
+			continue
+		fi
+		if [ -L "$_a_claim/$_a_name" ] && [ "$(readlink "$_a_claim/$_a_name")" = "$_a_text" ]; then
+			retired_claims="$retired_claims$_a_claim/$_a_name
+"
+		else
+			if ! unclaim "$_a_claim/$_a_name" "$_a_link"; then
+				retirement_error=1 retirement_restore_error=1
+				break
+			fi
+			err "PRESERVED: $_a_link changed during the setup and is left as it is"
+		fi
+	done
+	if [ -n "$created" ] || [ -n "$to_retire" ] || [ "$wrote" = 1 ] || { [ "$record" = 1 ] && [ "$new_hash" != "$st_hash" ]; }; then
+		# A retired module's link is gone once migrated; then the record drops its name.
+		_k_created=
+		for _k_name in $st_created; do
+			case " $RETIRED " in
+				*" $_k_name "*) owns_link "$skills_dir/$_k_name" "$_k_name" || continue ;;
+			esac
+			_k_created="$_k_created $_k_name"
+		done
+		new_created=$(printf '%s\n' $_k_created $created | LC_ALL=C sort -u | tr '\n' ' ')
 		new_created=${new_created# }
 		new_created=${new_created% }
 		# Of the folders this run meant to create, the ones that exist now, with the ones an
@@ -1011,7 +1111,7 @@ install() {
 		# makes a folder, and its undo keeps the rule it was made under.
 		want_dirs=1
 		if [ "$record" = 1 ] && [ -z "$st_has_dirs" ] && [ -z "$new_dirs" ]; then want_dirs=; fi
-		if ! write_state; then
+		if [ -n "$retirement_error" ] || ! write_state; then
 			for _a_done in $created; do remove_link "$skills_dir/$_a_done"; done
 			if [ "$wrote" = 1 ]; then
 				# Through a copy beside it and a rename, so a read-only file comes back as well.
@@ -1022,9 +1122,21 @@ install() {
 					rm -f "$target"
 				fi
 			fi
+			if ! printf '%s' "$retired_claims" | while IFS= read -r _a_claim; do
+				unclaim "$_a_claim" "$skills_dir/${_a_claim##*/}" || exit 1
+			done; then
+				die 4 "could not save the setup record $state; rollback incomplete; recovery claims were preserved"
+			fi
+			if [ -n "$retirement_restore_error" ]; then
+				die 4 "retired link restore failed; rollback incomplete; recovery claims were preserved"
+			fi
 			die 4 "could not save the setup record $state; the changes of this run were reversed"
 		fi
 	fi
+	printf '%s' "$retired_claims" | while IFS= read -r _a_claim; do
+		remove_link "$_a_claim" && rmdir "${_a_claim%/*}" 2>/dev/null
+		say "REMOVED_RETIRED: $skills_dir/${_a_claim##*/}"
+	done
 
 	# A home made for a record that was not needed goes again.
 	if [ ! -e "$state" ] && [ -n "$made_home" ]; then
@@ -1033,7 +1145,7 @@ install() {
 
 	# New links and a written instruction file are what a client has to be restarted for.
 	changed=0
-	if [ "$link_count" -gt 0 ] || [ "$wrote" = 1 ]; then changed=1; fi
+	if [ "$link_count" -gt 0 ] || [ "$wrote" = 1 ] || [ -n "$retired_claims" ]; then changed=1; fi
 	if [ "$changed" = 1 ]; then
 		say "INSTALLED: $source_line for $label"
 	else
@@ -1215,7 +1327,7 @@ undo() {
 	for _u_name in $st_created; do
 		_u_link=$st_dest/$_u_name
 		if [ -L "$_u_link" ]; then
-			if ! is_our_link "$_u_link" "$root/skills/$_u_name"; then
+			if ! owns_link "$_u_link" "$_u_name"; then
 				say "PRESERVED: changed target $_u_link"
 				exit 3
 			fi
@@ -1252,7 +1364,7 @@ undo() {
 	_u_removed=0
 	for _u_name in $st_created; do
 		_u_link=$st_dest/$_u_name
-		if is_our_link "$_u_link" "$root/skills/$_u_name"; then
+		if owns_link "$_u_link" "$_u_name"; then
 			remove_link "$_u_link" || die 4 "could not remove $_u_link"
 			_u_removed=$((_u_removed + 1))
 		fi

package/scripts/install_personalization.py

@@ -27,10 +27,17 @@ LEGACY_FLOW_INSTRUCTIONS = re.compile(
     r"\bnobrainer-ultra\b|^\s*#{1,6}\s+NoBrainer(?:[ .]?Tech)?\s+Flow\b",
     re.IGNORECASE | re.MULTILINE,
 )
-# The two lines that carry a standing authorization. --keep-options recognises a grant
+# The lines that carry a standing authorization. --keep-options recognises a grant
 # only as one of these exact lines, never as a phrase somewhere in the block, so free
 # text in a preference cannot forge one.
-AUTO_UPDATE_RULE = "- On the first `nobrainer-tech-flow` use each calendar day, check for a safe verified update when this client exposes a supported check. This setting grants standing authorization to apply a `nobrainer-tech-flow`-only update after verifying the canonical source/version, reviewing the exact changes, and making a recoverable backup. Never apply destructive, unrelated, or uncertain changes; ask the owner first. If the client is inactive or cannot check, do not claim a check occurred."
+AUTO_UPDATE_RULE = "- Once a day on first use, update nobrainer-tech-flow to its latest verified stable release from the canonical source, with a backup; change nothing else and ask if unsure."
+# The opt-out written by --no-auto-update.
+NOTIFY_UPDATE_RULE = "- Once a day on first use, tell the owner when a newer stable nobrainer-tech-flow release exists; do not update it yourself."
+# Lines written before 2.6.0. --keep-options maps them to the short rules above and
+# keeps the owner's choice: the old grant stays a grant, the old notify-only default
+# stays notify-only.
+LEGACY_AUTO_UPDATE_RULE = "- On the first `nobrainer-tech-flow` use each calendar day, check for a safe verified update when this client exposes a supported check. This setting grants standing authorization to apply a `nobrainer-tech-flow`-only update after verifying the canonical source/version, reviewing the exact changes, and making a recoverable backup. Never apply destructive, unrelated, or uncertain changes; ask the owner first. If the client is inactive or cannot check, do not claim a check occurred."
+LEGACY_NOTIFY_UPDATE_RULE = "- On the first `nobrainer-tech-flow` use each calendar day, check for available updates when this client exposes a supported check and notify the owner; do not apply them automatically. If the client is inactive or cannot check, do not claim a check occurred."
 AUTO_SESSION_RULE = "- This setting grants standing authorization for session rotation only when the host supports creating a fresh successor, context or checkpoint evidence warrants rotation, and no write is in flight. Create the successor, verify exact takeover by ID/readback, and archive the old session only after that readback. Do not create recursive visible workers or claim a restart when unsupported."
 
 
@@ -57,6 +64,28 @@ def earlier_grant(existing: str, rule: str, phrase: str, label: str, flag: str)
     return False
 
 
+# Wording of an update grant, current or pre-2.6, used only to warn that an edited one
+# was not kept.
+UPDATE_GRANT_PHRASES = (
+    "update nobrainer-tech-flow to its latest verified stable release",
+    "grants standing authorization to apply a `nobrainer-tech-flow`-only update",
+)
+
+
+def saved_update_choice(existing: str) -> bool:
+    """True only when an existing block holds an update grant as its own line.
+
+    Anything else, a notify-only line, an edited or unknown one, keeps notifying:
+    an update grant is never inferred. Trailing spaces on the line are ignored, and
+    a preference that quotes the wording is not a line of its own.
+    """
+
+    return any(
+        re.search(r"(?m)^" + re.escape(rule) + r"[ \t]*\r?$", existing) is not None
+        for rule in (AUTO_UPDATE_RULE, LEGACY_AUTO_UPDATE_RULE)
+    )
+
+
 def unsafe_line(value: str) -> bool:
     """True when ``value`` cannot be one plain Markdown line (or could split into two)."""
 
@@ -85,11 +114,7 @@ def build_block(
         if wiki_root is not None
         else "- At project start, discover whether a relevant wiki exists. If one exists, read its `WIKI.md`, locate relevant `index.md` entries with a targeted search, then read only the relevant pages. Ask before creating a wiki unless project rules or prior authorization already settle it."
     )
-    update_rule = (
-        AUTO_UPDATE_RULE
-        if auto_update
-        else "- On the first `nobrainer-tech-flow` use each calendar day, check for available updates when this client exposes a supported check and notify the owner; do not apply them automatically. If the client is inactive or cannot check, do not claim a check occurred."
-    )
+    update_rule = AUTO_UPDATE_RULE if auto_update else NOTIFY_UPDATE_RULE
     session_rule = (
         AUTO_SESSION_RULE
         if auto_session_restart
@@ -356,10 +381,16 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
         type=Path,
         help="project wiki root containing WIKI.md; its resolved path is added to the managed instructions",
     )
-    parser.add_argument(
+    updates = parser.add_mutually_exclusive_group()
+    updates.add_argument(
         "--auto-update",
         action="store_true",
-        help="authorize safe, verified nobrainer-tech-flow-only updates; default is check and notify",
+        help="update nobrainer-tech-flow once a day from its verified stable releases (the default)",
+    )
+    updates.add_argument(
+        "--no-auto-update",
+        action="store_true",
+        help="only tell the owner about a newer stable release; never update automatically",
     )
     parser.add_argument(
         "--auto-session-restart",
@@ -374,7 +405,7 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
         "--keep-options",
         action="store_true",
         help=(
-            "keep the auto-update, session-restart and wiki-root settings already in the "
+            "keep the update, session-restart and wiki-root settings already in the "
             "managed block; flags given on this run are added to them, never removed"
         ),
     )
@@ -429,15 +460,19 @@ def main(argv: list[str] | None = None) -> int:
             saved = SAVED_PREFERENCE.search(existing)
             if saved:
                 preferences = saved.group(1)
-        auto_update = args.auto_update
+        auto_update = not args.no_auto_update
         auto_session_restart = args.auto_session_restart
         if args.keep_options and existing:
             kept: list[str] = []
-            if not auto_update and earlier_grant(
-                existing, AUTO_UPDATE_RULE, "grants standing authorization to apply", "auto-update", "--auto-update"
-            ):
-                auto_update = True
-                kept.append("auto-update")
+            saved_update = saved_update_choice(existing)
+            if not (args.auto_update or args.no_auto_update) and not saved_update:
+                auto_update = False
+                kept.append("notify-only updates")
+                if any(phrase in existing for phrase in UPDATE_GRANT_PHRASES):
+                    print(
+                        "NOTE: an earlier update authorization was not kept because its line no longer "
+                        "matches what this installer writes; pass --auto-update to grant it again"
+                    )
             if not auto_session_restart and earlier_grant(
                 existing,
                 AUTO_SESSION_RULE,

package/scripts/install_skills.py

@@ -73,7 +73,7 @@ except ValueError:
 
 CURATED_SKILLS = frozenset(
     {
-        "nobrainer-codex-context",
+        "nobrainer-context",
         "nobrainer-skill-doctor",
         "nobrainer-autoimprove",
         "nobrainer-auto-fine-tune",
@@ -104,6 +104,7 @@ LEGACY_TO_CANONICAL = {
     "agents-restraint": "nobrainer-tech-flow",
     "codex-in-claude-code": "nobrainer-tech-flow",
     "code-autoresearch": "nobrainer-autoimprove",
+    "nobrainer-codex-context": "nobrainer-context",
     "deep-audit": "nobrainer-review",
     "deep-autoreview": "nobrainer-review",
     "deep-autoresearch": "nobrainer-autoimprove",
@@ -149,9 +150,11 @@ LEGACY_TO_CANONICAL = {
     "wiki-get": "nobrainer-wiki",
     "wiki-tidy": "nobrainer-wiki",
 }
-# Reddit integration was removed, not absorbed into a canonical skill. Keep its
-# owned-link migration, but a different source may legitimately use this name.
-RETIRED_LEGACY = frozenset({"nobrainer-reddit"})
+# Names Flow no longer ships: Reddit integration was removed, and
+# nobrainer-codex-context was renamed to nobrainer-context in 2.5.0 without an
+# alias. Keep their owned-link migration, but another source may legitimately
+# use these names, so a foreign target there is preserved, never removed.
+RETIRED_LEGACY = frozenset({"nobrainer-codex-context", "nobrainer-reddit"})
 UNMAPPED_LEGACY = frozenset({"nobrainer-fast-audit"})
 
 
@@ -455,6 +458,10 @@ def legacy_name_for(target: Path, canonical: Path) -> str | None:
     return None
 
 
+class ClaimRestoreError(RuntimeError):
+    """A changed entry was claimed but could not be restored to its original name."""
+
+
 def claim_legacy_link(
     target: Path, legacy_name: str
 ) -> tuple[Path, EntryFingerprint]:
@@ -484,7 +491,7 @@ def claim_legacy_link(
     try:
         restore_claim(target, claim)
     except RuntimeError as exc:
-        raise RuntimeError(
+        raise ClaimRestoreError(
             f"legacy link changed after preflight; {exc}"
         ) from exc
     raise RuntimeError(
@@ -683,6 +690,17 @@ def parse_args() -> argparse.Namespace:
             "root-level layout and renamed aliases."
         ),
     )
+    parser.add_argument(
+        "--recorded-retired",
+        action="append",
+        default=[],
+        metavar="NAME",
+        help=(
+            "A retired name that the calling setup's record lists as created by it: "
+            "its exact link into this checkout no longer blocks installation and is "
+            "left in place for that setup to retire once its whole run has succeeded."
+        ),
+    )
     return parser.parse_args()
 
 
@@ -748,6 +766,14 @@ def main() -> int:
             if legacy_name in RETIRED_LEGACY
             else "conflict"
         )
+        if (
+            state == "legacy"
+            and legacy_name in RETIRED_LEGACY
+            and legacy_name in args.recorded_retired
+        ):
+            # The setup record proves the setup made this link. The setup retires it
+            # after its own run succeeds; this helper never deletes it.
+            state = "recorded"
         alias_plan.append((legacy_name, canonical_name, target, state))
         if state == "conflict" or (state == "legacy" and not args.migrate_legacy):
             conflicts.append(target)
@@ -774,6 +800,9 @@ def main() -> int:
         print(f"{action}: {name}: {source} -> {target}")
 
     for legacy_name, canonical_name, target, state in alias_plan:
+        if state == "recorded":
+            print(f"RETIRED_RECORDED: {legacy_name}: made by this setup; renamed {canonical_name}: {target}")
+            continue
         if state == "preserved":
             print(
                 f"PRESERVED_FOREIGN: {legacy_name}: retired from nobrainer-tech-flow; "