nobrainer-tech-flow 2.4.1 → 2.6.0

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-build/SKILL.md

@@ -37,7 +37,9 @@ Apply these principles as decision rules, not slogans:
 
 - `KISS`: choose the simplest complete design that satisfies acceptance.
 - `YAGNI`: do not add extension points, compatibility layers or options for an
-  unproven future requirement.
+  unproven future requirement. Before adding complexity for a speculative race
+  or security edge case, name the concrete failure, its likelihood and the cost;
+  add it only when that case is accepted.
 - `DRY`: keep each rule and mutable fact under one owner, but do not abstract
   incidental similarity. Duplication can be cheaper than the wrong coupling.
 - `SOLID`: preserve cohesive responsibilities and stable dependency boundaries;
@@ -80,7 +82,9 @@ Reject a patch that contains any of the following without explicit acceptance:
 - duplicate state owners, speculative abstractions or fallback stacks that make
   failure ambiguous;
 - tests that only assert a mock/fixture while the real contract remains
-  unexercised.
+  unexercised;
+- in user interfaces, taglines, helper text and secondary labels added to explain
+  a screen; if the screen needs them, fix the layout.
 
 Names should explain intent. Comments should explain only non-obvious why,
 constraints, risk or tradeoffs. Do not create a new README, framework or process

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`.

package/skills/nobrainer-context/references/clients.md

@@ -0,0 +1,115 @@
+# What each client loads
+
+Checked against official documentation on 2026-10-20. Client behaviour changes;
+re-check the cited page before relying on a number, and report anything newer as
+fresh evidence. `UNVERIFIED` means the official pages read did not document it:
+treat it as unknown, never as a limit. `context_inventory.py` implements the
+project-local rules below.
+
+## Codex
+
+- Per directory from the project root (usually the Git root) down to the
+  working directory, at most one file: `AGENTS.override.md`, else `AGENTS.md`,
+  else the first name in `project_doc_fallback_filenames`. Files are joined
+  root first, so closer files appear later and win.
+- Global: `AGENTS.override.md` or `AGENTS.md` in `CODEX_HOME` (default
+  `~/.codex`).
+- Limit: `project_doc_max_bytes`, default 32 KiB; files past the limit are not
+  added. `project_root_markers` changes root detection; its default is
+  `UNVERIFIED` (the probe assumes `.git`).
+- Imports: none documented.
+- Readback: no command that prints the loaded instructions is documented
+  (`UNVERIFIED`); a model asked to list its sources is not a deterministic
+  readback. Use `codex_context.py` for the file chain.
+- Sources: <https://developers.openai.com/codex/guides/agents-md>,
+  <https://developers.openai.com/codex/config-reference>.
+
+## Claude Code
+
+- Project: `CLAUDE.md` or `.claude/CLAUDE.md`, and `CLAUDE.local.md` (personal,
+  gitignored), in the working directory and every directory above it, joined
+  root first; subdirectory files load when Claude works there.
+- Rules: `.claude/rules/**/*.md`. A rule without `paths:` frontmatter loads at
+  start; with `paths:` it loads only for matching files.
+- `AGENTS.md`: read directly (v2.1.277 or later) only when no `CLAUDE.md`,
+  `.claude/CLAUDE.md` or `CLAUDE.local.md` exists in the working directory or
+  above. Adding any of them stops that unless the user-level setting
+  `claude-md-and-agents-md` is chosen. A `CLAUDE.md` with `@AGENTS.md` works on
+  every version and never reads `AGENTS.md` twice.
+- Imports: `@path`, relative to the importing file, up to four hops; imported
+  files inherit the importing file's start-up or on-demand scope. With
+  `--include-global`, the probe also expands imports from the user-level
+  `~/.claude/CLAUDE.md`. Not expanded inside code spans or blocks.
+- Limits: guidance of under 200 lines per `CLAUDE.md`; the probe applies it to
+  directly discovered `CLAUDE.md` files, not imported files, `AGENTS.md` fallbacks
+  or `.claude/rules/*.md` rules. A file over 4 MiB is skipped.
+- Readback: `/context` (Memory files) and `/memory` in a fresh interactive
+  session; the `InstructionsLoaded` hook logs loads (not for `AGENTS.md` read
+  through the setting). `/doctor prompt-audit` (v2.1.283 or later) is a native
+  report of stale or conflicting instructions. No non-interactive command is
+  documented.
+- Source: <https://code.claude.com/docs/en/memory>.
+
+## Gemini CLI
+
+- `~/.gemini/GEMINI.md`, then `GEMINI.md` in the workspace directories and
+  their parents, then files found when a tool reads a directory. All are joined.
+- `context.fileName` in `settings.json` sets one name or a list, for example
+  `["AGENTS.md", "GEMINI.md"]`. The probe reads only project
+  `.gemini/settings.json`.
+- Imports: `@path`, default depth 5, circular imports blocked. With
+  `--include-global`, the probe also expands imports from the user-level
+  `~/.gemini/GEMINI.md`, using the same size, duplicate and goal-pointer checks.
+- Limit: none documented.
+- Readback: `/memory show` prints the combined memory.
+- Sources: <https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md>,
+  <https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/memport.md>.
+
+## Cursor
+
+- Project rules: `.cursor/rules`, `.mdc` files only (a plain `.md` there is
+  ignored), with `description`, `globs` and `alwaysApply` frontmatter.
+  `alwaysApply: true` applies to every request; the others attach by file
+  match, agent choice or manual mention.
+- `AGENTS.md` in the root and subdirectories; nested files combine with their
+  parents and the more specific one wins.
+- `.cursorrules`: not mentioned in the current docs (`UNVERIFIED`); the probe
+  reports it as legacy.
+- Limit: guidance to keep each rule under 500 lines.
+- Readback: none documented.
+- Sources: <https://cursor.com/docs/context/rules>,
+  <https://cursor.com/docs/cli/using>.
+
+## GitHub Copilot
+
+- `.github/copilot-instructions.md` (repository-wide) and
+  `.github/instructions/**/*.instructions.md` (path-specific, `applyTo`).
+- Agent files: `AGENTS.md` (nearest wins) and a root `CLAUDE.md` or `GEMINI.md`.
+- Support differs by surface: the cloud agent, the CLI and code review on
+  GitHub.com read all three kinds; VS Code chat reads `AGENTS.md` but not
+  `CLAUDE.md` or `GEMINI.md`; Copilot Chat on GitHub.com and code review in VS
+  Code and Visual Studio read only `copilot-instructions.md`.
+- Limit: none documented; a character limit for code review is `UNVERIFIED`.
+- Readback: none documented.
+- Sources: <https://docs.github.com/en/copilot/reference/custom-instructions-support>,
+  <https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions>,
+  <https://code.visualstudio.com/docs/copilot/customization/custom-instructions>.
+
+## OpenCode
+
+- Project: the first `AGENTS.md` found walking up from the working directory;
+  a `CLAUDE.md` only when no `AGENTS.md` exists. Global:
+  `~/.config/opencode/AGENTS.md`, else `~/.claude/CLAUDE.md`.
+- `instructions` in the project `opencode.json`: extra paths, globs or URLs, all
+  added. Config files may be JSON or JSONC (JSON with comments). The docs name
+  `opencode.jsonc` for managed settings; a project `opencode.jsonc` is
+  `UNVERIFIED`, and the probe reads it too. The probe resolves local paths and
+  globs and never fetches URLs. Source: <https://opencode.ai/docs/config/>.
+- Limit: none documented. Readback: none documented.
+- Source: <https://opencode.ai/docs/rules>.
+
+## Other clients
+
+The `AGENTS.md` format page lists further clients that read `AGENTS.md`
+(<https://agents.md>). Treat any client not covered above as `UNVERIFIED` until
+its own documentation is checked.

package/skills/nobrainer-context/references/consolidate.md

@@ -0,0 +1,66 @@
+# One source of truth with pointers
+
+Use this after an inventory, in `consolidate` or `repair` mode. Everything here
+is project-local and needs a preview and explicit approval before any write.
+
+## Choose the source of truth
+
+1. Prefer the root `AGENTS.md`: Codex, Cursor, GitHub Copilot's agent surfaces,
+   OpenCode and Claude Code (directly or through an import) can read it.
+2. If the project has no `AGENTS.md`, propose moving the shared content of the
+   largest current file into one, unless the team uses a single client and
+   says it does not want another file.
+3. Keep nested `AGENTS.md` files that hold real directory-specific rules; Codex
+   and Cursor combine them with the root file, and closer files win.
+
+## Reduce the other files
+
+| File | Keep | Pointer |
+|---|---|---|
+| `CLAUDE.md` | Claude-only lines | `@AGENTS.md` on its own line |
+| `.claude/CLAUDE.md` | Claude-only lines | `@../AGENTS.md`: imports resolve from the importing file's folder |
+| `CLAUDE.local.md` | personal, uncommitted lines | none; it stops Claude reading `AGENTS.md` directly, so keep the `@AGENTS.md` import in `CLAUDE.md` |
+| `GEMINI.md` | Gemini-only lines | `@AGENTS.md`, or `context.fileName` in project `.gemini/settings.json` listing `AGENTS.md` |
+| `.cursor/rules/*.mdc` | path- or task-scoped rules | none needed; Cursor reads `AGENTS.md` |
+| `.github/copilot-instructions.md` | lines for surfaces that ignore `AGENTS.md` (Copilot Chat on GitHub.com, code review in IDEs) | no import syntax; keep it short and non-contradictory |
+| `.github/instructions/*.instructions.md` | path-scoped rules with `applyTo` | none |
+| `opencode.json` / `opencode.jsonc` `instructions` | extra files OpenCode should add | entries only |
+
+Rules:
+
+- Keep each fact in one file. Delete a duplicate only after the source of truth
+  holds the same meaning; when the copies disagree, report the conflict and ask
+  which wording wins instead of picking one.
+- An import is not free: Claude Code and Gemini CLI load imported files at
+  start, so the import moves bytes, it does not remove them.
+- A sentence that only tells an agent to read another file is unreliable; use
+  the client's import or file-name setting when it has one.
+- A byte-identical copy (for example `CLAUDE.md` copied from `AGENTS.md`)
+  drifts, and GitHub Copilot's agent surfaces read both copies. Replace it with
+  the pointer unless the project requires the copy; a test that enforces the
+  copy is such a reason.
+- Preserve client-managed blocks (for example `NOBRAINER-TECH-FLOW` markers),
+  `AGENTS.override.md` precedence and every byte outside the lines you change.
+  A `NOBRAINER-CODEX-CONTEXT` block left by an earlier release is ordinary
+  project content: keep it, or fold its facts into the source of truth and
+  remove the markers in the same approved preview.
+- Never create a file a client does not read and call it loaded. A Codex
+  fallback name works only when `project_doc_fallback_filenames` lists it;
+  changing that global setting is a separate owner action.
+- Keep credentials, private machine paths, mutable runtime state, guessed
+  commands and model names out of instruction files.
+
+## Preview
+
+Show, for every file: the current bytes, the proposed bytes or a unified diff,
+and what each client in use will load afterwards with byte counts. Name the
+rollback: the exact preimage of each changed file (or a recoverable copy) and
+the files to delete if new. Wait for an explicit yes.
+
+## Apply and read back
+
+Write only the approved files, then run the inventory again. The change is
+`UPDATED` when the new inventory matches the preview: the same files per client,
+no new truncation, no import of a missing file, fewer or equal repeated lines and
+the goal pointer as proposed. Otherwise restore the preimages and report `BLOCKED` with the
+difference.