nobrainer-tech-flow 2.5.0 → 2.7.0

package/docs/releases/v2.6.0.md

@@ -0,0 +1,73 @@
+# nobrainer-tech-flow 2.6.0: delegate aggressively, verify by risk
+
+Release date: 2026-10-23.
+
+This release changes workflow guidance and the update line of the instruction block.
+The setup record and the module set (eighteen) do not change.
+
+## What changes
+
+- **Aggressive delegation as the default.** `skills/nobrainer-tech-flow/SKILL.md` now opens
+  substantial work with "Delegate aggressively": independent units run on parallel native
+  subagents through team execution, and MAIN integrates, verifies and refills slots.
+  `references/delivery.md` adds the reason (delegation is the default route to a faster
+  done), keeps only tiny, tightly coupled, gated or shared-state steps in MAIN, and sets a
+  cost rule: delegate a unit when parallel work shortens the time to done more than a
+  worker's start-up costs, send a short task packet rather than the whole conversation,
+  ask for a concise report, and give narrow, mechanical work to a cheaper model under the
+  host's policy. No model is named.
+- **Resend only failed units.** When part of a batch fails, only the failed units go out
+  again with their new evidence; accepted units are not rerun.
+- **Verification by blast radius.** `references/delivery.md` scales verification to how
+  risky and reversible a change is. Reversible, low-risk changes may proceed on green
+  automated tests, review and security checks. CI configuration, credentials,
+  security-sensitive paths, data migrations and irreversible effects need an independent
+  review and remain owner-gated. An agent's approval never counts as the owner's.
+- **Two build rules.** `skills/nobrainer-build/SKILL.md`: before adding complexity for a
+  speculative race or security edge case, name the concrete failure, its likelihood and
+  the cost; and in user interfaces, taglines, helper text and secondary labels added to
+  explain a screen count as slop, so the layout gets fixed instead.
+
+## Daily updates by default, in one line
+
+The managed instruction block now carries one short update line, on by default for new
+setups: "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."
+`install_personalization.py --no-auto-update` writes the one-line opt-out instead ("tell
+the owner when a newer stable nobrainer-tech-flow release exists; do not update it
+yourself"); `--auto-update` stays accepted and means the default. With `--keep-options`
+(which `install.py` and the guided setup always pass) the longer lines written before 2.6.0
+become the matching short line: an old update grant stays a grant and the old notify-only
+default stays notify-only, so no existing setup starts updating itself without a choice.
+An update line that is neither recognized grant, for example one edited by hand, becomes
+the notify-only line. `install.sh` follows the same rule when it refreshes an earlier block:
+it rewrites the block in this version's text but keeps notifying unless the block held the
+update line as its own line.
+
+## Sources
+
+The delegation rule is an owner decision (2026-10-23). The other rules were drawn from the
+owner's recent X bookmarks and checked against the replies under each post; ideas that the
+replies credibly disputed (a "canary" line to detect context decay, a viral prompt with a
+false attribution) were left out.
+
+## Verification record
+
+Local checks (macOS, Python 3.14.5):
+
+- `python3 scripts/validate_skills.py` and `python3 scripts/validate_skills.py --suite`: OK.
+- `skills/nobrainer-tech-flow/SKILL.md` stays within the suite budget (239 lines, 1,749
+  words; limits 240 and 1,750).
+- `python3 -m unittest tests.test_suite tests.test_delegation_contract
+  tests.test_visible_session_rule`: 81 tests OK.
+- `python3 -m unittest tests.test_shell_installer tests.test_personalization
+  tests.test_one_command_installer tests.test_guided_onboarding`: OK, including the new
+  cases for the default update line, the opt-out, pre-2.6 blocks, edited or unknown update
+  lines and preferences that quote the update wording.
+- `sh -n`, `dash -n` and `shellcheck -S error` on `scripts/install.sh`: clean.
+- `git diff --check`: clean.
+- An independent read-only review found four issues in the update-line handling and its
+  documentation (an unrecognized notify-only line could turn into an update grant); all
+  were fixed and a second review pass confirmed the fixes.
+
+The full suite runs in the Validate workflow for the tagged commit.

package/docs/releases/v2.7.0.md

@@ -0,0 +1,145 @@
+# nobrainer-tech-flow 2.7.0: delegation where it pays, owner requests in the goal file
+
+Release date: 2026-10-25.
+
+This release changes workflow guidance and delegation, the optional Claude Code guards,
+`nobrainer-team`, `nobrainer-security` and `nobrainer-build`. The setup record and the module set (eighteen) do not change.
+
+## What changes
+
+- **Done is defined and visible.** `skills/nobrainer-tech-flow/SKILL.md` now has the
+  agent show the owner what done means before substantial work and set it as the
+  host-native goal where supported; `references/delivery.md`, `references/project-start.md`
+  and `references/long-run-state.md` replace "create a native goal only when explicitly
+  requested" with "set the outcome and DoD as the native goal when the host offers one",
+  so the owner can see whether the goal is running, paused or stopped. The Markdown goal
+  stays the canonical, portable record. The TODO stays visible: the canonical TODO is
+  mirrored in the host's plan or todo tool when it has one, otherwise shown as the
+  Progress checklist (`SKILL.md`, `references/delivery.md`, `references/setup.md`).
+- **Delegation only where it pays.** `references/delivery.md` "Coordinated team
+  execution" now makes one MAIN loop that loads skills on demand the default. A unit
+  goes to a native worker only when parallel work, context isolation, independent
+  verification or specialization outweighs the cost, and the plan names that condition;
+  without one, the unit stays in MAIN. Work is split by context, not by type of work, so
+  the worker that changes a feature also writes and runs its tests. The 2.6.0 rules that
+  made delegation the default and said a missing measured speedup was no reason to keep
+  work in MAIN are removed. An owner or host rule that asks for more delegation still
+  controls. `SKILL.md`, `AGENTS.md`, `CLAUDE.md`, `nobrainer-team`,
+  `nobrainer-auto-fine-tune`, `references/model-routing.md` (`STANDARD` is now the
+  default and `ROUTED` applies only to qualifying units), `references/long-run-state.md`,
+  the shared bootstrap, the Copilot instructions, the
+  personalization block written by the installers, the README and the workflow diagram
+  say the same. The change follows Anthropic's published guidance:
+  [when to fold subagents into the main agent loop](https://claude.com/resources/articles/building-agents-when-to-fold-subagents-into-your-main-agent-loop)
+  and [when multi-agent systems help](https://www.claude.com/blog/building-multi-agent-systems-when-and-how-to-use-them),
+  which reports that multi-agent implementations typically use three to ten times more
+  tokens than a single agent for equivalent tasks.
+- **Owner requests go into the goal file as they arrive.** In
+  `skills/nobrainer-tech-flow/SKILL.md` the detailed-ledger gate has a new condition: the
+  owner keeps adding requests mid-run in one long conversation. A new section of
+  `references/long-run-state.md`, "New owner requests", sets the rule. While the ledger is
+  active, the agent records each new request or idea before it continues any work, even
+  when the request is deferred. The row quotes the owner's words (minus any secret) and
+  carries the date and the status `PENDING`, or `READY` when nothing blocks it. When the
+  gate first passes mid-conversation, earlier unfinished requests are backfilled. Rows are
+  reconciled at every checkpoint, after compaction and at closeout, and none is silently
+  dropped. At closeout each row is `ACCEPTED`, `STOPPED` with the owner decision that
+  stopped it, or visibly open with its next step. In `references/correction-hooks.md`,
+  `OWNER_DECISION_CHANGED` now acts as soon as the change arrives, before other work,
+  updates the goal-file row when a ledger is active, and keeps other project instruction
+  files from carrying the old rule: under `AUTO_SCOPED` it edits the contradicting line,
+  under `ASK` it prepares the exact diff and asks once, and under `OFF` it names the stale
+  line in the final report. The goal-file block gains `CURRENT_MILESTONE`: one short-term
+  goal derived from `OUTCOME` and the open request rows, small enough to finish and verify
+  in the current session. The agent works toward it without waiting, sets the next
+  milestone from the open rows when it is accepted, and re-derives it at once when the
+  owner changes a decision or a new request changes what matters most; accepting a
+  milestone never closes `OUTCOME`. `OWNER_DECISION_CHANGED` resumes on that re-derived
+  milestone. The default task-local goal file is
+  `.nobrainer/goal.md`, which the context inventory already searches; it should not be
+  committed to a public repository. The short restatements of the gate in
+  `references/routing.md`, `references/setup.md`, `AGENTS.md`, `CLAUDE.md` and the
+  README say the same.
+- **The guards point back to the goal file after compaction.** The optional Claude Code
+  guards gain a fourth hook, SessionStart with the matcher `compact|resume|clear`. It
+  tells the agent to re-read up to three active Flow goal files: files with a `GOAL_ID:`
+  line and a `STATUS` other than `COMPLETE` in the project root, `tasks/`, `docs/` or
+  `.nobrainer/`. It prints only each path and a known `STATUS` word, never other
+  goal-file text. It follows no symlink, skips unusual file names, stops after 5,000
+  folder entries or 200 files, and prints nothing on any error.
+  `scripts/install_guards.py` now reports an install from an earlier version as an
+  update. If you already use the guards, update your Git checkout to 2.7.0 first, so the
+  hooks' `flow_guard.py` knows the new mode, then preview the change with
+  `python3 scripts/install.py --client claude --guards`, apply it with `--apply` and
+  restart Claude Code. Until then the three earlier hooks keep working unchanged. The hook
+  only finds goal files that already exist; it does not write one.
+- **Team uses task-local specialists, not third-party skills.** `nobrainer-team` no
+  longer searches for, downloads, installs or runs external skills, and it writes into no
+  client's skill folder. When a capability gap remains after curated skills, installed
+  skills, project tools and bounded research, MAIN writes a specialist brief (role,
+  method from project docs or verified primary sources, allowed actions, write scope,
+  acceptance and report) for a native worker. The brief stays in the task plan and is
+  discarded afterwards. The module's description now says "task-local specialist briefs".
+- **A clean security result needs more than one pass.** In
+  `skills/nobrainer-security/SKILL.md` one model pass counts as a sample of the scope, not
+  as coverage. Before `CLEAN`, at least one more independent pass starts from a different
+  entry point, trust boundary or data-flow direction; the review stops when a pass adds no
+  new verified finding and reports how many passes ran. After a fix, when the defect was
+  public or reachable before it, the agent checks the available logs or other evidence for
+  exploitation during that exposure window, or lists the window under
+  `UNTESTED_OR_INACCESSIBLE_SURFACE`. In `references/delivery.md` the security-sensitive
+  paths that need an independent review and stay owner-gated, however small the diff, now
+  name authentication, permissions, payments and personal data. Work from an untrusted or
+  unknown author never takes the low-risk path, and a user-interface change needs rendered
+  evidence, a screenshot or recording, before and after where possible; unit tests alone
+  do not prove it.
+- **Stale conventions are reported, not followed silently.** In
+  `skills/nobrainer-build/SKILL.md`, when instruction files or docs describe a coding
+  convention that the existing code does not follow, the agent follows the convention the
+  code uses, unless the instruction is an explicit owner rule or names a deliberate
+  migration, and lists each disagreement in its final report. When the code wins, the
+  report includes the exact edit that fixes the stale instruction file, applied only as
+  the project's `LEARNING_WRITE_POLICY` allows, so the next run does not inherit the stale
+  rule; when an owner rule or migration wins, it names the code change required. Owner
+  rules on safety, authority and workflow always apply.
+- **Accurate install documentation.** The README lists the free remote MCP server
+  (`https://mcp.nobrainer.tech/mcp`, no sign-in, stateless, six read-only tools) as a
+  sixth channel and says it does not install the eighteen modules. `docs/CHAT_PLUGINS.md`
+  and `docs/INSTALL.md` now say the npm package is published.
+- **Test fixes.** The bounded-runner interrupt test waits until the child's pid file
+  holds a number, not only until it exists, which removes an intermittent CI failure.
+  A duplicate GitHub transport test that shadowed another one was removed.
+
+## The remote MCP server
+
+The MCP server in `mcp/` is deployed separately and is not part of the npm package.
+Since 2.6.0 it returns a goal-file block with a renewed contract token when
+`get_flow_step` is called with a contract token and `event: "resume"`, and a scheduled, read-only workflow
+warns three days before the bundled model-advisor benchmark snapshot expires. Its
+guidance cards are still pinned to 2.6.0 and move to this release in a separate change
+after the tag.
+
+## Verification record
+
+Local checks (macOS, Python 3.14):
+
+- `python3 scripts/validate_skills.py` and `python3 scripts/validate_skills.py --suite`: OK.
+- `skills/nobrainer-tech-flow/SKILL.md` stays within the suite budget (239 lines, 1,748
+  words; limits 240 and 1,750); `AGENTS.md` and `CLAUDE.md` stay byte-identical within
+  theirs (205 lines, 1,615 words; limits 205 and 1,620).
+- `python3 -m unittest tests.test_suite`: 74 tests OK. Every other test module, run
+  separately: OK.
+- `git diff --check`: clean.
+- An independent read-only review of this release preparation found three issues: the
+  always-loaded instructions went over their word budget, the guard upgrade steps were
+  incomplete, and the release text overstated what the request rule guarantees. All three
+  were fixed. Two further independent read-only reviews of the delegation, security and
+  conventions changes found four low and two medium issues: README summaries that dropped
+  conditions, tests that did not protect the exceptions or the cost gate, and the
+  delegation-first default still present in `nobrainer-auto-fine-tune` and
+  `references/model-routing.md`. All were fixed, and a test now checks that the retired
+  delegation defaults do not return on the active surfaces.
+
+The changes it ships were each reviewed and passed CI in their own pull requests (#98,
+#101, #109, #110, #111, #112, #113, #115). The full suite runs in the Validate workflow for the
+tagged commit.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "nobrainer-tech-flow",
   "description": "From task to done. nobrainer-tech-flow is one workflow of 18 modules for AI coding agents: it scopes the task, delegates ready work, checks the result and hands over the evidence, including what was not checked.",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "contextFileName": "GEMINI.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nobrainer-tech-flow",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "From task to done. nobrainer-tech-flow is one workflow of 18 modules for AI coding agents: it scopes the task, delegates ready work, checks the result and hands over the evidence, including what was not checked.",
   "type": "module",
   "main": ".opencode/plugins/nobrainer-tech-skills.js",

package/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "nobrainer-tech-flow",
   "description": "From task to done. nobrainer-tech-flow is one workflow of 18 modules for AI coding agents: it scopes the task, delegates ready work, checks the result and hands over the evidence, including what was not checked.",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "author": {
     "name": "NoBrainer Tech",
     "url": "https://nobrainer.tech"

package/scripts/install.py

@@ -4,7 +4,9 @@
 Every run is a dry run until --apply. The skills are linked and the managed
 instruction block is written by the same helpers as the manual and guided setups,
 and --undo uses the guided setup's rollback state (as scripts/install.sh does), so
-every path reverses the same way. This command never grants a standing authorization.
+every path reverses the same way. The only standing authorization it writes is the
+default daily update of Flow itself, and an existing block keeps notifying unless it
+already held that update line.
 """
 
 from __future__ import annotations

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)
@@ -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() {
@@ -56,12 +63,14 @@ block() {
 
 - Use the `nobrainer-tech-flow` module as the task entrypoint when this client supports skill invocation, by the exact name this client lists for it. In Codex that is `$nobrainer-tech-flow:nobrainer-tech-flow` when modules are listed under the plugin name, or `$nobrainer-tech-flow` when they are listed plainly. If unavailable, check the documented installation path and report that limitation honestly.
 - On first setup, load `nobrainer-auto-fine-tune` for a read-only capability audit; preserve MAIN model and effort, and mark unverified runtime values `UNKNOWN`.
-- Preserve the user's selected MAIN model and effort. Inspect the host's actual subagent models, capabilities, concurrency and quota; delegate every independent ready unit promptly and refill slots after audited completion. Keep coordination in MAIN. Never assume a model is available or silently substitute one.
+- Preserve the user's selected MAIN model and effort. Inspect the host's actual subagent models, capabilities, concurrency and quota; work in one MAIN loop and delegate only units that gain from parallel work, context isolation, independent review or specialization. Keep coordination in MAIN. Never assume a model is available or silently substitute one.
 - Split substantial work into bounded tasks with clear outputs, exclusive write scope, dependencies, and verification. Keep integration and acceptance in MAIN; avoid duplicate or filler tasks.
 - 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
@@ -806,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
@@ -827,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")
@@ -836,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" |
@@ -873,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:"
@@ -881,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/^/+/'

package/scripts/install_guards.py

@@ -1,14 +1,16 @@
 #!/usr/bin/env python3
 """Preview, add or remove the optional nobrainer-tech-flow guards for Claude Code.
 
-The guards are three hooks in the Claude Code user settings.json: a PreToolUse hook
-that asks before common risky shell commands, and Stop and SubagentStop hooks that
-ask for a proof line once. Every run is a preview until --apply. The hooks point at
-flow_guard.py through the skill link that scripts/install.py created, so they keep
-working when the checkout is updated. Our entries are the hooks whose command is
-exactly one this script generates; --undo --apply removes those and nothing else.
-The preview names only those hooks and the settings path, never other settings,
-which can hold tokens.
+The guards are four hooks in the Claude Code user settings.json: a PreToolUse hook
+that asks before common risky shell commands, Stop and SubagentStop hooks that ask
+for a proof line once, and a SessionStart hook that, after compaction, resume or
+clear, names the active Flow goal files to re-read. Every run is a preview until
+--apply, and an install from an earlier version is reported as an update. The hooks
+point at flow_guard.py through the skill link that scripts/install.py created, so
+they keep working when the checkout is updated. Our entries are the hooks whose
+command is exactly one this script generates; --undo --apply removes those and
+nothing else. The preview names only those hooks and the settings path, never other
+settings, which can hold tokens.
 """
 
 from __future__ import annotations
@@ -28,8 +30,14 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parents[1]
 INSTALL_SKILLS = ROOT / "scripts" / "install_skills.py"
 GUARD = Path("nobrainer-tech-flow") / "scripts" / "flow_guard.py"
-EVENTS = (("PreToolUse", "Bash", "pre-tool"), ("Stop", None, "stop"), ("SubagentStop", None, "stop"))
+EVENTS = (
+    ("PreToolUse", "Bash", "pre-tool"),
+    ("Stop", None, "stop"),
+    ("SubagentStop", None, "stop"),
+    ("SessionStart", "compact|resume|clear", "session"),
+)
 TIMEOUT = 10
+DONE = {"add": "INSTALLED", "update": "UPDATED", "remove": "REMOVED"}
 DISCLAIMER = (
     "NOTE: a seatbelt: it asks before common risky commands; it is not a security "
     "boundary, and sh -c or variables bypass it."
@@ -223,18 +231,26 @@ def run(apply: bool, undo: bool, home: Path | None, rerun: str = "python3 script
             print(f"UP TO DATE: the Flow guards are already in {settings_path}; nothing changed")
         return 0
     after = render(updated)
+    # Some of our hooks but not exactly the current set, as an install from an earlier
+    # version leaves them: an update, never reported as current.
+    present = len(listed(settings, guard))
+    action = "remove" if undo else "update" if present else "add"
     if not apply:
         hooks = listed(settings if undo else updated, guard)
-        verb = f"remove {len(hooks)} hooks from" if undo else f"add {len(hooks)} hooks to"
-        print(f"PREVIEW: would {verb} {settings_path}; other settings keep their values:")
+        target = {
+            "remove": f"remove {len(hooks)} hooks from {settings_path}",
+            "update": f"update the Flow guards in {settings_path} ({present} hooks now, {len(hooks)} after)",
+            "add": f"add {len(hooks)} hooks to {settings_path}",
+        }[action]
+        print(f"PREVIEW: would {target}; other settings keep their values:")
         print("\n".join(hooks))
         if not undo:
             print(DISCLAIMER)
         flags = "--undo --apply" if undo else "--apply"
-        print(f"NO_CHANGES: preview only; {'remove' if undo else 'add'} them with: {rerun.replace('{flags}', flags)}")
+        print(f"NO_CHANGES: preview only; {action} them with: {rerun.replace('{flags}', flags)}")
         return 0
     backup = write(settings_path, before, after)
-    print(f"{'REMOVED' if undo else 'INSTALLED'}: Flow guards in {settings_path}")
+    print(f"{DONE[action]}: Flow guards in {settings_path}")
     if backup:
         print(f"BACKUP: {backup}")
     if not undo:

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
@@ -105,7 +130,7 @@ def build_block(
 
 - Use the `nobrainer-tech-flow` module as the task entrypoint when this client supports skill invocation, by the exact name this client lists for it. In Codex that is `$nobrainer-tech-flow:nobrainer-tech-flow` when modules are listed under the plugin name, or `$nobrainer-tech-flow` when they are listed plainly. If unavailable, check the documented installation path and report that limitation honestly.
 - On first setup, load `nobrainer-auto-fine-tune` for a read-only capability audit; preserve MAIN model and effort, and mark unverified runtime values `UNKNOWN`.
-- Preserve the user's selected MAIN model and effort. Inspect the host's actual subagent models, capabilities, concurrency and quota; delegate every independent ready unit promptly and refill slots after audited completion. Keep coordination in MAIN. Never assume a model is available or silently substitute one.
+- Preserve the user's selected MAIN model and effort. Inspect the host's actual subagent models, capabilities, concurrency and quota; work in one MAIN loop and delegate only units that gain from parallel work, context isolation, independent review or specialization. Keep coordination in MAIN. Never assume a model is available or silently substitute one.
 - Split substantial work into bounded tasks with clear outputs, exclusive write scope, dependencies, and verification. Keep integration and acceptance in MAIN; avoid duplicate or filler tasks.
 - 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.
 {wiki_rule}
@@ -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/skills/nobrainer-auto-fine-tune/SKILL.md

@@ -27,7 +27,7 @@ Keep advertised, configured, callable, and successfully invoked capabilities dis
 
 For a one-off, low-risk task, use the owner's selected MAIN and current known tools; skip benchmarking and state that routing is uncalibrated. For a recurring workflow, material model choice, or task with meaningful quality/latency/cost tradeoffs, define a small bounded comparison before spending resources.
 
-Classify the work by required expertise, context, accuracy, latency, cost sensitivity, confidentiality, dependence between units, and integration effort. Calibration follows the delegation-first default for independent units with measurable acceptance and disjoint write scope. A missing benchmark or measured speed gain does not block eligible dispatch. When comparing routes, measure the critical path and observed concurrency, including setup, review and integration; worker count alone proves no benefit.
+Classify the work by required expertise, context, accuracy, latency, cost sensitivity, confidentiality, dependence between units, and integration effort. MAIN is the default; calibration compares worker routes only for units that qualify under [team execution](../nobrainer-tech-flow/references/delivery.md#coordinated-team-execution) and have measurable acceptance and disjoint write scope. A missing benchmark does not block a qualifying unit's dispatch. When comparing routes, measure the critical path and observed concurrency, including setup, review and integration; worker count alone proves no benefit.
 
 ## Run a bounded, comparable calibration
 

package/skills/nobrainer-build/SKILL.md

@@ -26,6 +26,17 @@ Before the first write, resolve:
 - cheapest useful failing proof, target tests, broader verifier/build/runtime;
 - side effects, owner gates, rollback and the `Done clean` condition.
 
+When instruction files or docs describe a coding convention the existing code
+does not follow, do not pick one silently. Follow the convention the code uses,
+unless the instruction is an explicit owner rule or names a deliberate migration,
+and list each disagreement in the final report. When the code's convention wins,
+include the exact edit that would bring the stale instruction file in line, and
+apply it only as the project's `LEARNING_WRITE_POLICY` allows
+([correction hooks](../nobrainer-tech-flow/references/correction-hooks.md)), so the
+next run does not inherit the stale rule. When an owner rule or migration wins,
+name the code change it requires instead. Owner rules on safety, authority and
+workflow always apply.
+
 Preserve unrelated changes. Use an isolated worktree or disjoint write scope
 when another writer is active. If a missing requirement changes architecture,
 scope, public behavior or safety, stop at `SPEC_CHANGE_PROPOSED`; do not invent it
@@ -37,7 +48,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 +93,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-security/SKILL.md

@@ -137,6 +137,11 @@ constraint, deployment setting, parser behavior or version fact that would make
 the path unreachable. Reject generic hardening, style preferences, stale
 advisories for another version and speculative chains missing a necessary step.
 
+One model pass samples the scope; it does not prove coverage. Before `CLEAN`,
+run at least one more independent pass that starts from a different entry point,
+trust boundary or data-flow direction. Stop when a pass adds no new verified
+finding, and report how many passes ran.
+
 ## Handoff and remediation
 
 Security review ends with evidence and a fix contract. If remediation is in
@@ -146,6 +151,11 @@ security trace with fresh evidence. Consequential fixes still require an
 independent `nobrainer-review` or release gate; self-authored code is not
 self-approved.
 
+A fix closes the path; it does not show the path was never used. When the
+defect was public or reachable before the fix, check the available logs or
+other evidence for exploitation during that exposure window. If that evidence
+is unavailable, list the window under `UNTESTED_OR_INACCESSIBLE_SURFACE`.
+
 ## Final report
 
 ```text