nobrainer-tech-flow 2.4.0 → 2.5.0

package/scripts/install.sh

@@ -19,7 +19,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 +28,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:]_]|$)'
@@ -169,7 +169,9 @@ physical() {
 			return
 		fi
 	done
-	_p_head=$(cd -P "$_p_head" 2>/dev/null && pwd -P) || _p_head=$1 _p_tail=
+	# The slash keeps a trailing line break of a folder name across the substitution.
+	_p_head=$(cd -P "$_p_head" 2>/dev/null && printf '%s/' "$PWD") || _p_head=$1/ _p_tail=
+	_p_head=${_p_head%/}
 	printf '%s%s\n' "${_p_head%/}" "$_p_tail"
 }
 
@@ -283,6 +285,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() (
@@ -408,7 +442,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
@@ -543,7 +578,9 @@ under_link() {
 # The folders a record lists must be ones the setup can have made: each an absolute,
 # plain path listed once, that is, or lies above, the skills folder, the folder of the
 # instruction file or the folder of the record. Anything else is a damaged record that an undo must not act on. A path
-# may be spelled with or without the links on the way, so both spellings count.
+# may be spelled with or without the links on the way, so both spellings count. Two entries
+# may still lead to one folder: a link put in place of one of them since the setup does that.
+# The undo removes no folder of such a group.
 above() {
 	case "$2/" in "$1"/*) return 0 ;; esac
 	return 1
@@ -591,9 +628,9 @@ check_dirs() {
 			fi
 			[ -n "$_k_ok" ] || exit 1
 			case $_k_seen in *"
-$_k_real
+$_k_dir
 "*) exit 1 ;; esac
-			_k_seen="$_k_seen$_k_real
+			_k_seen="$_k_seen$_k_dir
 "
 		done
 	}
@@ -677,7 +714,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"
@@ -704,7 +741,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"
@@ -815,6 +858,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
@@ -910,6 +956,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
@@ -922,6 +972,16 @@ install() {
 	sha256 /dev/null >/dev/null || die 2 "this script needs sha256sum, shasum or openssl to record the setup"
 
 	created= dirs_to_make=
+	# A folder this run makes is recorded as it really is, links resolved. A line break or a
+	# control character in that form would leave a record no undo can read, so such a run
+	# stops before anything is written.
+	note_dirs "$home"
+	if [ "$link_count" -gt 0 ]; then note_dirs "$skills_dir"; fi
+	if [ "$file_status" != present ] && [ "$inherit" = 0 ]; then note_dirs "${target%/*}"; fi
+	printf '%s' "$dirs_to_make" | while IFS= read -r _a_dir; do
+		reject_control "$(physical "$_a_dir")" "the real path of $_a_dir"
+	done || exit 2
+	dirs_to_make=
 	# The record's folder is made before anything else is written: when it cannot be made,
 	# the run stops here instead of leaving links and a block that no record describes. It
 	# counts among the folders the setup made: a home that does not exist yet is made for
@@ -972,8 +1032,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
@@ -997,7 +1092,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.
@@ -1008,9 +1103,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
@@ -1019,7 +1126,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
@@ -1201,7 +1308,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
@@ -1238,7 +1345,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
@@ -1283,9 +1390,23 @@ undo() {
 	rm -f "$state"
 	# The record is gone, so the folder it sat in may be empty now. A folder that was there
 	# before the setup is not listed, and a folder that holds anything stays.
+	# Two entries that lead to one folder cannot both be what the setup made, and the record
+	# cannot say which one is, so no entry of such a group is removed. The groups are found
+	# before any folder goes.
 	_u_gone=
 	if [ -n "$st_dirs" ]; then
+		_u_dupes=$(printf '%s' "$st_dirs" | while IFS= read -r _u_dir; do physical "$_u_dir"; done | LC_ALL=C sort | uniq -d)
+		_u_shared=
+		if [ -n "$_u_dupes" ]; then
+			_u_shared=$(printf '%s' "$st_dirs" | while IFS= read -r _u_dir; do
+				if printf '%s\n' "$_u_dupes" | grep -q -x -F -e "$(physical "$_u_dir")"; then printf '%s\n' "$_u_dir"; fi
+			done)
+		fi
 		_u_gone=$(printf '%s' "$st_dirs" | LC_ALL=C sort -r | while IFS= read -r _u_dir; do
+			if [ -n "$_u_shared" ] && printf '%s\n' "$_u_shared" | grep -q -x -F -e "$_u_dir"; then
+				printf 'PRESERVED: %s: another folder in the record leads to the same folder, so it is left as it is\n' "$_u_dir"
+				continue
+			fi
 			if [ ! -d "$_u_dir" ] || [ -L "$_u_dir" ]; then continue; fi
 			if under_link "$_u_dir"; then
 				printf 'PRESERVED: %s: a folder above it is a link now, so it is left as it is\n' "$_u_dir"

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; "