nobrainer-tech-flow 2.4.1 → 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:]_]|$)'
@@ -285,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() (
@@ -410,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
@@ -681,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"
@@ -708,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"
@@ -819,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
@@ -914,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
@@ -986,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
@@ -1011,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.
@@ -1022,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
@@ -1033,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
@@ -1215,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
@@ -1252,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

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

package/scripts/recommend_flow_setup.py

@@ -107,6 +107,85 @@ def recorded_setting(client: str, home: Path, destination: object, target: objec
     return None
 
 
+def recorded_skill(name: object) -> bool:
+    """A name a setup record may hold: a current module, or one a release retired."""
+
+    return isinstance(name, str) and (name in BY_SKILL or name in _sibling(INSTALL_SKILLS).RETIRED_LEGACY)
+
+
+def owns_link(target: Path, name: str) -> bool:
+    """True when target is this checkout's link for name; a retired module's link dangles."""
+
+    if name in BY_SKILL:
+        return links_to(target, SKILLS_DIR / name)
+    return _sibling(INSTALL_SKILLS).is_exact_legacy_link(target, name)
+
+
+def recorded_retired_args(record: dict | None) -> list[str]:
+    """install_skills.py flags for retired modules a setup record says this setup linked."""
+
+    names = (record or {}).get("created_skills", [])
+    return [arg for name in names if isinstance(name, str) and name not in BY_SKILL for arg in ("--recorded-retired", name)]
+
+
+def claim_retired_links(destination: Path, record: dict | None) -> list[tuple[Path, Path, tuple]]:
+    """Move the retired links a record lists aside, verifying each moved entry.
+
+    The claim is install_skills.py's atomic claim-and-verify: an entry that changed after
+    the check is put back untouched. The claims are deleted only once the whole setup run
+    has succeeded, and put back on any failure before that.
+    """
+
+    skills = _sibling(INSTALL_SKILLS)
+    claims = []
+    try:
+        for name in (record or {}).get("created_skills", []):
+            if not isinstance(name, str) or name in BY_SKILL:
+                continue
+            target = destination / name
+            if not skills.is_exact_legacy_link(target, name):
+                continue
+            try:
+                claim, expected = skills.claim_legacy_link(target, name)
+            except skills.ClaimRestoreError:
+                raise
+            except RuntimeError as exc:
+                print(f"PRESERVED: {target} changed during the setup and is left as it is ({exc})")
+                continue
+            claims.append((target, claim, expected))
+    except (OSError, skills.ClaimRestoreError) as exc:
+        errors = restore_retired_links(claims)
+        if errors:
+            raise skills.ClaimRestoreError(f"{exc}; {'; '.join(errors)}") from exc
+        raise
+    return claims
+
+
+def restore_retired_links(claims: list[tuple[Path, Path, tuple]]) -> list[str]:
+    """Put claimed retired links back; return what could not be restored."""
+
+    errors = []
+    for target, claim, expected in reversed(claims):
+        try:
+            # Moves the entry back without replacing a new one, and removes the private folder.
+            _sibling(INSTALL_SKILLS).restore_claim(target, claim, expected)
+        except (OSError, RuntimeError) as exc:
+            errors.append(f"retired link restore failed: {exc}")
+    return errors
+
+
+def commit_retired_links(claims: list[tuple[Path, Path, tuple]]) -> None:
+    """Delete the claimed retired links once the setup run has succeeded."""
+
+    for target, claim, expected in claims:
+        if _sibling(INSTALL_SKILLS).entry_fingerprint(claim) == expected:
+            claim.unlink()
+            claim.parent.rmdir()
+            print(f"REMOVED_RETIRED: {target}")
+        else:
+            print(f"BACKUP_PRESERVED: the claimed retired link changed and is kept: {claim}")
+
+
 def links_to(target: Path, source: Path) -> bool:
     """True when target is a symlink resolving to source; loops and dangling links are not."""
 
@@ -144,7 +223,7 @@ ITEMS = (
     Item("14", "nobrainer-spec-driven-development", "Specifications", ("software-development", "product"), "define durable contracts for architectural changes"),
     Item("15", "nobrainer-rca", "Root-cause analysis", ("software-development", "operations"), "diagnose repeated or causally unclear failures"),
     Item("16", "nobrainer-team", "Capability-to-role design", ("software-development", "operations"), "assign available capabilities to bounded work"),
-    Item("17", "nobrainer-codex-context", "Project context", ("software-development", "operations"), "inspect and maintain project instructions and context"),
+    Item("17", "nobrainer-context", "Project instructions", ("software-development", "operations"), "one tidy set of project instructions for every coding agent"),
     Item("18", "nobrainer-wiki", "Durable knowledge", ("research", "product", "operations"), "query and maintain a sourced project knowledge base"),
 )
 BY_ID = {item.id: item for item in ITEMS}
@@ -604,10 +683,10 @@ def run(command: list[str], hide: tuple[str, ...] = ()) -> tuple[int, str]:
 
 def remove_exact_created_links(destination: Path, names: list[str]) -> None:
     for name in names:
-        if name not in BY_SKILL:
+        if not recorded_skill(name):
             continue
         target = destination / name
-        if links_to(target, SKILLS_DIR / name):
+        if owns_link(target, name):
             target.unlink()
 
 
@@ -783,7 +862,7 @@ def read_state_file(path: Path) -> dict[str, object]:
         or not isinstance(loaded.get("destination"), str)
         or not isinstance(loaded.get("created_skills"), list)
         or not isinstance(loaded.get("profile"), dict)
-        or any(not isinstance(name, str) or name not in BY_SKILL for name in loaded.get("created_skills", []))
+        or not all(recorded_skill(name) for name in loaded.get("created_skills", []))
     ):
         raise ValueError(f"refusing to overwrite unrecognized setup state: {path}")
     try:
@@ -997,7 +1076,7 @@ def rollback(args: argparse.Namespace, state_file: Path) -> int:
         return 3
     destination = Path(state["destination"])
     created = state.get("created_skills", [])
-    if not isinstance(created, list) or len(created) != len(set(created)) or any(name not in BY_SKILL for name in created):
+    if not isinstance(created, list) or len(created) != len(set(created)) or not all(recorded_skill(name) for name in created):
         print("ERROR: rollback state contains invalid skill ownership entries", file=sys.stderr)
         return 3
     try:
@@ -1066,7 +1145,7 @@ def rollback(args: argparse.Namespace, state_file: Path) -> int:
     for name in created:
         target = destination / name
         if target.is_symlink():
-            if not links_to(target, SKILLS_DIR / name):
+            if not owns_link(target, name):
                 print(f"PRESERVED: changed target {target}")
                 return 3
         elif target.exists():
@@ -1086,8 +1165,7 @@ def rollback(args: argparse.Namespace, state_file: Path) -> int:
     removed: list[str] = []
     for name in created:
         target = destination / name
-        source = SKILLS_DIR / name
-        if links_to(target, source):
+        if owns_link(target, name):
             target.unlink()
             removed.append(name)
         elif target.exists() or target.is_symlink():
@@ -1384,7 +1462,7 @@ def main(argv: list[str] | None = None) -> int:
         # Inspect every target before writing any of them. This keeps a later
         # conflict from leaving a partial selection installed.
         for name in install_names:
-            command = [sys.executable, str(ROOT / "scripts" / "install_skills.py"), "--client", args.client, "--dest", str(destination), "--skill", name]
+            command = [sys.executable, str(ROOT / "scripts" / "install_skills.py"), "--client", args.client, "--dest", str(destination), "--skill", name, *recorded_retired_args(previous)]
             code, _ = run(command, hide=("NOTE: ",))
             if code:
                 return code
@@ -1394,7 +1472,7 @@ def main(argv: list[str] | None = None) -> int:
         profile_preimage = read_file_preimage(profile_target)
         if args.apply:
             for name in install_names:
-                command = [sys.executable, str(ROOT / "scripts" / "install_skills.py"), "--client", args.client, "--dest", str(destination), "--skill", name, "--apply"]
+                command = [sys.executable, str(ROOT / "scripts" / "install_skills.py"), "--client", args.client, "--dest", str(destination), "--skill", name, "--apply", *recorded_retired_args(previous)]
                 code, _ = run(command, hide=("NOTE: ",))
                 if code:
                     remove_exact_created_links(destination, new_skills)
@@ -1428,7 +1506,9 @@ def main(argv: list[str] | None = None) -> int:
                 "backup": recorded_backup,
                 "written_sha256": hashlib.sha256(profile_target.read_bytes()).hexdigest(),
             }
-        created = sorted(set(previous.get("created_skills", [])) | {name for name in new_skills if (destination / name).is_symlink()})
+        # A retired module's link is gone once retired; then the record drops its name.
+        kept = {name for name in previous.get("created_skills", []) if name in BY_SKILL or owns_link(destination / name, name)}
+        created = sorted(kept | {name for name in new_skills if (destination / name).is_symlink()})
         next_state = {"destination": str(destination), "created_skills": created, "profile": profile}
         # Folders an earlier run made stay in the record as recorded, links already resolved
         # then. Resolving them again would follow a link put in their place since, and hand the
@@ -1443,10 +1523,18 @@ def main(argv: list[str] | None = None) -> int:
         # a run makes a folder, so that its undo follows the rule it was made under.
         if created_dirs or not previous or "created_dirs" in previous:
             next_state["created_dirs"] = created_dirs
+        # The retired links the record lists go last, after every other write, and come back
+        # if the record cannot be saved.
+        retired_claims = []
         try:
+            retired_claims = claim_retired_links(destination, previous)
+            retired_names = {target.name for target, _, _ in retired_claims}
+            next_state["created_skills"] = [name for name in created if name not in retired_names]
             save_state(state, next_state)
-        except (OSError, TypeError, ValueError) as exc:
+        except (OSError, RuntimeError, TypeError, ValueError) as exc:
             rollback_errors: list[str] = []
+            if isinstance(exc, _sibling(INSTALL_SKILLS).ClaimRestoreError):
+                rollback_errors.append(str(exc))
             if profile.get("target") and "APPLIED: " in profile_output:
                 restore_preimage = profile_preimage
                 if backup_match:
@@ -1483,6 +1571,7 @@ def main(argv: list[str] | None = None) -> int:
                 remove_exact_created_links(destination, new_skills)
             except OSError as rollback_exc:
                 rollback_errors.append(f"skill rollback failed: {rollback_exc}")
+            rollback_errors.extend(restore_retired_links(retired_claims))
             remaining_links = [
                 name
                 for name in new_skills
@@ -1507,6 +1596,7 @@ def main(argv: list[str] | None = None) -> int:
             detail = f"{exc}; rollback incomplete: {'; '.join(rollback_errors)}" if rollback_errors else f"{exc}; applied changes were rolled back and read back"
             print(f"ERROR: setup state save failed: {detail}", file=sys.stderr)
             return 3 if rollback_errors else 2
+        commit_retired_links(retired_claims)
         after = installed_ids(destination)
         actual_added = sorted(after - before)
         expected_added = sorted(BY_SKILL[name].id for name in new_skills)

package/scripts/validate_skills.py

@@ -18,7 +18,7 @@ LINK_RE = re.compile(r"\[[^\]]+\]\((?!https?://|#|mailto:)([^)]+)\)")
 
 SUITE = {
     "nobrainer-auto-fine-tune": "nb-auto-fine-tune",
-    "nobrainer-codex-context": "nb-codex-context",
+    "nobrainer-context": "nb-context",
     "nobrainer-skill-doctor": "nb-skill-doctor",
     "nobrainer-tech-flow": "NBFlow",
     "nobrainer-team": "nb-team",
@@ -69,6 +69,7 @@ LEGACY = {
     "nb-write",
     "nobrainer-autopilot",
     "nobrainer-capture-lesson",
+    "nobrainer-codex-context",
     "nobrainer-continuous-improvement",
     "nobrainer-memory",
     "nobrainer-memory-memsearch",

package/skills/nobrainer-context/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: nobrainer-context
+description: "Use when the owner says nb-context or asks to set up, audit or tidy one project's instructions for coding agents (AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, Copilot instructions): find what each client loads and its size against documented limits, report duplicates and contradictions, then propose one source of truth with short pointers, applied only after approval and read back."
+---
+
+# NoBrainer Context
+
+Keep one tidy set of project instructions that every coding agent in use reads.
+This module owns the project-instruction boundary of one repository: which files
+each client loads, what they cost, where they repeat or disagree, and one
+consolidation change. It does not own model selection, global client settings,
+session transfer, goal tracking or the delivery workflow.
+
+## Select a mode
+
+- `inspect` (default) - inventory and report. Do not write.
+- `consolidate` - inspect, propose one source of truth with pointers, show the
+  exact preview, wait for explicit approval, apply project-local edits only,
+  then inspect again.
+- `repair` - fix one known defect, such as a duplicate managed block, a dangling
+  import or a truncated Codex chain. Do not rewrite unrelated instructions.
+
+A question gets `inspect`. Use `consolidate` only when the owner asks to tidy or
+set up the project's instructions. Findings are evidence to report, not
+permission to edit.
+
+## 1. Inventory what each client loads
+
+Run the bundled read-only probe from the project with Python 3.11+, replacing
+`<context-skill-dir>` with this module's directory:
+
+```bash
+python3 <context-skill-dir>/scripts/context_inventory.py --json
+```
+
+It lists, per client (Codex, Claude Code, Gemini CLI, Cursor, GitHub Copilot,
+OpenCode), the files loaded at start, on demand or by import, with bytes, lines
+and words; the Codex byte budget and truncation; files over documented line
+guidance; byte-identical copies; lines repeated across files; imports of missing
+files; settings or Codex configuration it cannot parse; and the Flow goal pointer
+state. Instructions in folders below the current one are listed as on demand and
+left out of the start-up totals. Add `--include-global` to include each client's
+user-level file and, for Claude and Gemini, its recursive imports in the same
+size, duplicate and goal-pointer checks. Claude's 200-line guidance applies only
+to `CLAUDE.md` files discovered directly, not imported files, `AGENTS.md` fallbacks
+or `.claude/rules/*.md` rules. Use `--client NAME` to narrow the report and
+`--goal-file PATH` for an explicit goal file.
+`scripts/codex_context.py --check --json` keeps the detailed Codex chain probe.
+
+The probe applies the rules in [clients.md](references/clients.md). Only those
+documented behaviours count; anything marked `UNVERIFIED` there is reported as
+unknown, never as a limit. Ask which clients the team actually uses when the
+files alone do not say, and drop the others from the report.
+
+## 2. Report duplicates and contradictions
+
+Repeated lines come from the probe. Contradictions need reading: compare the
+files a client loads together for different commands, package managers, test
+gates, branch rules, languages or tone, and for a file that tells the agent to
+read another file in words instead of importing it. Report each with exact
+`file:line` pairs. This step is report-only.
+
+## 3. Propose one source of truth
+
+Follow [consolidate.md](references/consolidate.md). The usual shape is
+`AGENTS.md` as the source of truth, `CLAUDE.md` holding `@AGENTS.md` plus only
+Claude-specific lines, and each other client's file reduced to a pointer or to
+the lines that client alone needs. Show the full preview (new bytes or a diff
+per file), what each client will load afterwards and the rollback, then wait
+for explicit approval. Apply only inside the project. Never edit global
+instruction files, `~/.codex/config.toml`, `~/.gemini/settings.json`, client
+settings, credentials or plugin installs unless the owner asks for that
+separate action.
+
+## 4. Read back
+
+After a change, run the probe again and compare it with the preview. That is a
+file-level readback. Mark `RUNTIME_READBACK: VERIFIED` only from a client's own
+output that lists loaded files in a fresh session, as listed per client in
+[clients.md](references/clients.md); otherwise `UNKNOWN`. A probe exit code or
+an installed module does not prove a client followed the instructions.
+
+## 5. Goal pointer
+
+When the project keeps a Flow goal file (`GOAL_ID:` block, see
+[long-run state](../nobrainer-tech-flow/references/long-run-state.md)), check
+that the instructions name the current one and no stale or missing goal path.
+Propose the one-line pointer fix in the same preview. Goal content, status and
+handoff stay with `nobrainer-tech-flow` and `nobrainer-sessions`.
+If no active goals remain, the pointer state is `NONE`, including when completed
+goals are still mentioned; a pointer to a missing file remains `STALE_POINTER`.
+
+## Closeout
+
+```text
+CONTEXT: CURRENT | ATTENTION | UPDATED | BLOCKED
+PROJECT_ROOT: <path or UNKNOWN>
+CLIENTS: <client: loaded files and bytes, one per line>
+LIMITS: <truncated or over-guidance files, or NONE>
+DUPLICATES: <count and top file:line pairs, or NONE>
+CONTRADICTIONS: <file:line pairs, or NONE>
+SOURCE_OF_TRUTH: <file, or NOT_PROPOSED>
+GOAL_POINTER: NONE | POINTED | NOT_POINTED | STALE_POINTER
+PROJECT_WRITE: NONE | <files changed>
+RUNTIME_READBACK: VERIFIED | UNKNOWN | UNSUPPORTED
+OWNER_ACTION_REQUIRED: <one exact action or NONE>
+ROLLBACK: <exact preimages or NOT_APPLICABLE>
+```
+
+Route audits across many projects or skill portfolios to
+`nobrainer-skill-doctor`, broader setup and delivery to `nobrainer-tech-flow`,
+context transfer to `nobrainer-sessions` and release closeout to
+`nobrainer-review`.