nobrainer-tech-flow 2.4.1 → 2.6.0

package/skills/nobrainer-context/scripts/context_inventory.py

@@ -0,0 +1,425 @@
+#!/usr/bin/env python3
+"""Read-only inventory of the project instruction files coding agents load.
+
+Lists, per client, the instruction files it reads in one project, their size
+against documented limits, lines repeated across files, which file imports
+which, and whether instructions point to the current Flow goal file. It never
+writes. Client rules and sources: ../references/clients.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import hashlib
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import codex_context  # noqa: E402
+
+CLIENTS = ("codex", "claude", "gemini", "cursor", "copilot", "opencode")
+# Documented guidance, not hard limits (see references/clients.md).
+LINE_GUIDANCE = {"claude": 200, "cursor": 500}
+CLAUDE_HARD_BYTES = 4 * 1024 * 1024
+IMPORT_DEPTH = {"claude": 4, "gemini": 5}
+# Modes that put a file in context at session start (Copilot: agent surfaces only).
+LOADED = ("launch", "import", "global", "agent_surfaces")
+MIN_DUPLICATE_CHARS = 40
+MAX_READ_BYTES = 4 * 1024 * 1024
+IMPORT_RE = re.compile(r"(?:^|\s)@((?:~/|\.{0,2}/)?[\w.\-/]*\w)")
+GOAL_ID_RE = re.compile(r"^GOAL_ID:\s*\S", re.MULTILINE)
+GOAL_STATUS_RE = re.compile(r"^STATUS:\s*([A-Z_]+)", re.MULTILINE)
+GOAL_DIRS = ("", "tasks", "docs", ".nobrainer")
+
+
+def global_file(client: str) -> Path | None:
+    """The first user-level instruction file the client documents, if present."""
+
+    env = os.environ
+    codex = Path(env.get("CODEX_HOME") or "~/.codex").expanduser()
+    claude = Path(env.get("CLAUDE_CONFIG_DIR") or "~/.claude").expanduser()
+    config = Path(env.get("XDG_CONFIG_HOME") or "~/.config").expanduser()
+    candidates = {
+        "codex": (codex / "AGENTS.override.md", codex / "AGENTS.md"),
+        "claude": (claude / "CLAUDE.md",),
+        "gemini": (Path("~/.gemini/GEMINI.md").expanduser(),),
+        "copilot": (Path("~/.copilot/copilot-instructions.md").expanduser(),),
+        "opencode": (config / "opencode" / "AGENTS.md", Path("~/.claude/CLAUDE.md").expanduser()),
+    }.get(client, ())
+    return next((path for path in candidates if path.is_file()), None)
+
+
+def read_bytes(path: Path) -> bytes | None:
+    try:
+        return path.read_bytes()
+    except OSError:
+        return None
+
+
+def read_text(path: Path) -> str:
+    try:
+        with path.open("rb") as handle:
+            return handle.read(MAX_READ_BYTES).decode("utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def chain(root: Path, cwd: Path) -> list[Path]:
+    return codex_context.search_dirs(root, cwd)
+
+
+def prose(text: str) -> str:
+    """Text outside fenced code blocks and inline code spans."""
+
+    # Blank fenced blocks but keep their line breaks, so line numbers stay true.
+    text = re.sub(r"^(```|~~~).*?^\1", lambda m: "\n" * m.group(0).count("\n"), text,
+                  flags=re.MULTILINE | re.DOTALL)
+    return re.sub(r"`[^`\n]*`", "", text)
+
+
+def imports(path: Path, depth: int, seen: set[Path] | None = None,
+            missing: list[tuple[Path, int, str]] | None = None) -> list[Path]:
+    """Files path imports with @path, recursively; unresolved path-like imports go to missing."""
+
+    seen = seen if seen is not None else {path.resolve()}
+    found: list[Path] = []
+    if depth <= 0:
+        return found
+    for number, line in enumerate(prose(read_text(path)).splitlines(), 1):
+        for match in IMPORT_RE.finditer(line):
+            name = match.group(1)
+            target = (Path(name).expanduser() if name.startswith("~") else path.parent / name).resolve()
+            if not target.is_file():
+                # A path, not a handle such as @alice: it names a file that is not there.
+                if missing is not None and ("/" in name or re.search(r"\.[A-Za-z0-9]+$", name)):
+                    missing.append((path, number, name))
+                continue
+            if target not in seen:
+                seen.add(target)
+                found.append(target)
+                found.extend(imports(target, depth - 1, seen, missing))
+    return found
+
+
+def frontmatter(path: Path) -> str:
+    text = read_text(path)
+    if not text.startswith("---"):
+        return ""
+    end = text.find("\n---", 3)
+    return text[3:end] if end > 0 else ""
+
+
+def present(*paths: Path) -> list[Path]:
+    return [path for path in paths if path.is_file()]
+
+
+def strip_jsonc(text: str) -> str:
+    """JSON from JSONC: comments outside strings and trailing commas removed."""
+
+    out: list[str] = []
+    index, quoted = 0, False
+    while index < len(text):
+        char = text[index]
+        if quoted:
+            out.append(char)
+            if char == "\\":
+                out.append(text[index + 1:index + 2])
+                index += 1
+            elif char == '"':
+                quoted = False
+        elif char == '"':
+            quoted = True
+            out.append(char)
+        elif text.startswith("//", index):
+            end = text.find("\n", index)
+            index = len(text) if end < 0 else end
+            continue
+        elif text.startswith("/*", index):
+            end = text.find("*/", index + 2)
+            if end < 0:
+                raise ValueError("unterminated block comment")
+            out.append(" ")
+            index = end + 2
+            continue
+        else:
+            out.append(char)
+        index += 1
+    # Match complete strings first so comma/bracket bytes in paths stay literal.
+    return re.sub(r'"(?:\\.|[^"\\])*"|,(\s*[}\]])',
+                  lambda match: match.group(1) if match.group(1) is not None else match.group(0),
+                  "".join(out))
+
+
+def project_settings(path: Path, problems: list[str], client: str, root: Path) -> dict[str, Any]:
+    """A project settings file as a dict; a file that cannot be parsed is a problem."""
+
+    if not path.is_file():
+        return {}
+    try:
+        value = json.loads(strip_jsonc(read_text(path)))
+    except ValueError as exc:
+        problems.append(f"{client}: {label(path, root)} cannot be parsed: {exc}")
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+SKIP_DIRS = {"node_modules", "vendor", "dist", "build", "target", "venv", "__pycache__"}
+MAX_DESCENDANT_DIRS = 5000
+
+
+def descendants(cwd: Path) -> list[Path]:
+    """Folders below cwd that may hold scoped instructions; hidden and vendored ones skipped."""
+
+    found: list[Path] = []
+    for current, names, _ in os.walk(cwd):
+        names[:] = sorted(n for n in names if not n.startswith(".") and n not in SKIP_DIRS)
+        if Path(current) != cwd:
+            found.append(Path(current))
+        if len(found) >= MAX_DESCENDANT_DIRS:
+            break
+    return found
+
+
+def client_files(client: str, root: Path, cwd: Path, codex_config: Path,
+                 problems: list[str], include_global: bool = False) -> list[tuple[Path, str]]:
+    """Return (file, load mode) pairs one client reads for this project.
+
+    Problems found on the way (a settings file that cannot be parsed, an import of a
+    file that does not exist) are appended to problems.
+    """
+
+    dirs = chain(root, cwd)
+    below = descendants(cwd)
+    files: list[tuple[Path, str]] = []
+    if client == "codex":
+        result = codex_context.inspect_context(cwd, codex_config)
+        problems.extend(f"codex: {error}" for error in result["config_errors"])
+        files = [(Path(doc["path"]), "launch") for doc in result["documents"]]
+    elif client == "claude":
+        # Claude Code reads every folder from the filesystem root down, not only the project.
+        home = Path.home().resolve()
+        ancestors = list(reversed([cwd, *cwd.parents]))
+
+        def claude_names(folder: Path) -> list[Path]:
+            # ~/.claude/CLAUDE.md is the user file: it loads anyway and does not stop AGENTS.md.
+            dot = [] if folder == home else [folder / ".claude" / "CLAUDE.md"]
+            return present(folder / "CLAUDE.md", *dot, folder / "CLAUDE.local.md")
+
+        claude = [p for d in ancestors for p in claude_names(d)]
+        agents = [p for d in ancestors for p in present(d / "AGENTS.md", d / ".claude" / "AGENTS.md")]
+        files = [(p, "launch") for p in (claude or agents)]
+        for rule in sorted((root / ".claude" / "rules").rglob("*.md")):
+            scoped = re.search(r"^paths\s*:", frontmatter(rule), re.MULTILINE)
+            files.append((rule, "on_demand" if scoped else "launch"))
+        for folder in below:
+            own = claude_names(folder)
+            files += [(p, "on_demand") for p in own or (present(folder / "AGENTS.md") if not claude else [])]
+    elif client == "gemini":
+        settings = project_settings(root / ".gemini" / "settings.json", problems, client, root)
+        names = settings.get("context", {})
+        names = names.get("fileName", "GEMINI.md") if isinstance(names, dict) else "GEMINI.md"
+        names = [names] if isinstance(names, str) else [n for n in names if isinstance(n, str)] or ["GEMINI.md"]
+        files = [(p, "launch") for d in dirs for p in present(*(d / n for n in names))]
+        files += [(p, "on_demand") for d in below for p in present(*(d / n for n in names))]
+    elif client == "cursor":
+        for rule in sorted((root / ".cursor" / "rules").rglob("*.mdc")):
+            always = re.search(r"^alwaysApply\s*:\s*true", frontmatter(rule), re.MULTILINE)
+            files.append((rule, "launch" if always else "conditional"))
+        files += [(p, "launch") for d in dirs for p in present(d / "AGENTS.md")]
+        files += [(p, "conditional") for d in below for p in present(d / "AGENTS.md")]
+        files += [(p, "legacy") for p in present(root / ".cursorrules")]
+    elif client == "copilot":
+        files = [(p, "launch") for p in present(root / ".github" / "copilot-instructions.md")]
+        files += [(p, "conditional") for p in sorted((root / ".github" / "instructions").rglob("*.instructions.md"))]
+        nearest = [p for d in reversed(dirs) for p in present(d / "AGENTS.md")][:1]
+        files += [(p, "agent_surfaces") for p in nearest + present(root / "CLAUDE.md", root / "GEMINI.md")]
+        files += [(p, "conditional") for d in below for p in present(d / "AGENTS.md")]
+    elif client == "opencode":
+        up = list(reversed(dirs))
+        agents = [p for d in up for p in present(d / "AGENTS.md")][:1]
+        files = [(p, "launch") for p in agents or [p for d in up for p in present(d / "CLAUDE.md")][:1]]
+        for config in ("opencode.json", "opencode.jsonc"):
+            entries = project_settings(root / config, problems, client, root).get("instructions", [])
+            for entry in entries if isinstance(entries, list) else []:
+                if not isinstance(entry, str) or not entry.strip() or entry.startswith(("http://", "https://")):
+                    continue
+                pattern = os.path.join(str(root), os.path.expanduser(entry))
+                files += [(Path(p), "launch") for p in sorted(glob.glob(pattern, recursive=True)) if Path(p).is_file()]
+    user_file = global_file(client) if include_global else None
+    if user_file is not None:
+        files.append((user_file, "global"))
+    depth = IMPORT_DEPTH.get(client, 0)
+    missing: list[tuple[Path, int, str]] = []
+    expanded: list[tuple[Path, str]] = []
+    for path, mode in files:
+        expanded.append((path, mode))
+        import_mode = "import" if mode in LOADED else mode
+        expanded += [(extra, import_mode) for extra in imports(path, depth, missing=missing)]
+    for path, number, name in dict.fromkeys(missing):
+        problems.append(f"{client}: {label(path, root)}:{number} imports {name}, which does not exist")
+    unique: dict[Path, tuple[Path, str]] = {}
+    for path, mode in expanded:
+        key = path.resolve()
+        if key not in unique or (mode in LOADED and unique[key][1] not in LOADED):
+            unique[key] = (path, mode)
+    return list(unique.values())
+
+
+def normalize(line: str) -> str:
+    line = re.sub(r"^\s*(?:[-*+]|\d+[.)])\s+", "", line.strip())
+    return re.sub(r"\s+", " ", line).lower()
+
+
+def duplicates(paths: list[Path], root: Path) -> list[dict[str, Any]]:
+    seen: dict[str, list[str]] = {}
+    for path in paths:
+        for number, line in enumerate(prose(read_text(path)).splitlines(), 1):
+            key = normalize(line)
+            if len(key) >= MIN_DUPLICATE_CHARS and not key.startswith(("#", "<!--", "|")):
+                where = f"{label(path, root)}:{number}"
+                if not any(item.startswith(label(path, root) + ":") for item in seen.setdefault(key, [])):
+                    seen[key].append(where)
+    return [{"text": key[:100], "locations": spots} for key, spots in seen.items() if len(spots) > 1]
+
+
+def label(path: Path, root: Path) -> str:
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        home = Path.home().resolve()
+        resolved = path.resolve()
+        return "~/" + resolved.relative_to(home).as_posix() if resolved.is_relative_to(home) else str(resolved)
+
+
+def describe(path: Path, root: Path) -> dict[str, Any]:
+    data = read_bytes(path)
+    raw = data or b""
+    text = raw.decode("utf-8", errors="replace")
+    return {
+        "path": label(path, root),
+        "readable": data is not None,
+        "bytes": len(raw),
+        "lines": text.count("\n") + (0 if text.endswith("\n") or not text else 1),
+        "words": len(text.split()),
+        "sha256": hashlib.sha256(raw).hexdigest(),
+        "imports": [label(p, root) for p in imports(path, 1)],
+    }
+
+
+def goal_state(root: Path, texts: dict[str, str], explicit: Path | None) -> dict[str, Any]:
+    candidates = [explicit] if explicit else [
+        path for sub in GOAL_DIRS for pattern in ("*.md", "*/*.md")
+        for path in sorted((root / sub).glob(pattern)) if sub or pattern == "*.md"
+    ]
+    goals = []
+    for path in candidates:
+        text = read_text(path) if path and path.is_file() and path.stat().st_size <= 256 * 1024 else ""
+        if GOAL_ID_RE.search(text):
+            status = GOAL_STATUS_RE.search(text)
+            goals.append({"path": label(path, root), "status": status.group(1) if status else "UNKNOWN"})
+    active = [g for g in goals if g["status"] not in ("COMPLETE",)]
+    mentioned = {g["path"] for g in goals for t in texts.values() if g["path"] in t}
+    dangling = sorted({m for t in texts.values() for m in re.findall(r"[\w./-]*goal[\w./-]*\.md", t, re.I)
+                       if not (root / m).is_file()})
+    if not active:
+        status = "STALE_POINTER" if dangling else "NONE"
+    elif any(g["path"] in mentioned for g in active):
+        status = "POINTED"
+    else:
+        status = "STALE_POINTER" if mentioned or dangling else "NOT_POINTED"
+    return {"status": status, "goal_files": goals, "mentioned": sorted(mentioned), "missing_paths": dangling}
+
+
+def inventory(cwd: Path, codex_config: Path, clients: tuple[str, ...], include_global: bool,
+              goal_file: Path | None) -> dict[str, Any]:
+    root, _ = codex_context.find_root(cwd, codex_context.DEFAULT_MARKERS)
+    root = root or cwd
+    report: dict[str, Any] = {"schema": 1, "project_root": str(root), "clients": {}}
+    all_files: dict[Path, Path] = {}
+    findings: list[str] = []
+    for client in clients:
+        loaded = client_files(client, root, cwd, codex_config, findings, include_global)
+        entries = []
+        for path, mode in loaded:
+            all_files.setdefault(path.resolve(), path)
+            entry = describe(path, root) | {"mode": mode}
+            if not entry["readable"]:
+                findings.append(f"{client}: {entry['path']} cannot be read")
+            guidance = LINE_GUIDANCE.get(client)
+            if client == "claude" and path.name != "CLAUDE.md":
+                guidance = None
+            entry["over_guidance"] = bool(guidance and mode != "import" and entry["lines"] > guidance)
+            if entry["over_guidance"]:
+                findings.append(f"{client}: {entry['path']} has {entry['lines']} lines (guidance {guidance})")
+            if client == "claude" and entry["bytes"] > CLAUDE_HARD_BYTES:
+                findings.append(f"claude: {entry['path']} is over 4 MiB and is skipped")
+            entries.append(entry)
+        doubled = duplicates([p for p, m in loaded if m in LOADED], root)
+        if doubled:
+            findings.append(f"{client}: {len(doubled)} line(s) loaded more than once")
+        info: dict[str, Any] = {"files": entries, "launch_bytes": sum(
+            e["bytes"] for e in entries if e["mode"] in LOADED), "repeated_lines": len(doubled)}
+        if client == "codex":
+            probe = codex_context.inspect_context(cwd, codex_config)
+            info |= {"byte_budget": probe["project_doc_max_bytes"], "truncated": probe["status"] == "TRUNCATED"}
+            if info["truncated"]:
+                findings.append("codex: project instructions exceed project_doc_max_bytes and are truncated")
+        report["clients"][client] = info
+    paths = list(all_files.values())
+    report["files"] = sorted({label(p, root) for p in paths})
+    digests: dict[str, list[str]] = {}
+    for path in paths:
+        data = read_bytes(path)
+        if data is not None:
+            digests.setdefault(hashlib.sha256(data).hexdigest(), []).append(label(path, root))
+    report["identical_copies"] = [sorted(group) for group in digests.values() if len(group) > 1]
+    report["duplicates"] = duplicates(paths, root)
+    report["goal"] = goal_state(root, {label(p, root): read_text(p) for p in paths}, goal_file)
+    if report["identical_copies"]:
+        findings.append(f"{len(report['identical_copies'])} set(s) of byte-identical instruction files")
+    if report["goal"]["status"] in ("NOT_POINTED", "STALE_POINTER"):
+        findings.append(f"goal: {report['goal']['status']}")
+    source = root / "AGENTS.md"
+    report["source_of_truth_candidate"] = "AGENTS.md" if source.is_file() else None
+    report["findings"] = findings
+    report["status"] = "MISSING" if not paths else "ATTENTION" if findings else "CURRENT"
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--cwd", type=Path, default=Path.cwd())
+    parser.add_argument("--codex-config", type=Path, help="Codex config.toml (default: CODEX_HOME or ~/.codex)")
+    parser.add_argument("--client", action="append", choices=CLIENTS, help="limit to a client; repeatable")
+    parser.add_argument("--include-global", action="store_true", help="also size each client's user-level file")
+    parser.add_argument("--goal-file", type=Path, help="Flow goal file to check instead of searching")
+    parser.add_argument("--json", action="store_true", help="print machine-readable JSON")
+    parser.add_argument("--check", action="store_true", help="exit 1 unless the status is CURRENT")
+    args = parser.parse_args()
+    cwd = args.cwd.expanduser().resolve()
+    config = (args.codex_config or Path(os.environ.get("CODEX_HOME", "~/.codex")) / "config.toml").expanduser()
+    goal = args.goal_file.expanduser().resolve() if args.goal_file else None
+    report = inventory(cwd, config.resolve(), tuple(args.client or CLIENTS), args.include_global, goal)
+    if args.json:
+        print(json.dumps(report, indent=2, sort_keys=True))
+    else:
+        print(f"CONTEXT: {report['status']}")
+        print(f"PROJECT_ROOT: {report['project_root']}")
+        for client, info in report["clients"].items():
+            names = ", ".join(f"{e['path']} ({e['mode']}, {e['bytes']} B)" for e in info["files"]) or "NONE"
+            print(f"{client.upper()}: {names}")
+        print(f"IDENTICAL_COPIES: {report['identical_copies'] or 'NONE'}")
+        print(f"REPEATED_LINES: {len(report['duplicates'])}")
+        print(f"GOAL: {report['goal']['status']}")
+        for finding in report["findings"]:
+            print(f"FINDING: {finding}")
+    return 1 if args.check and report["status"] != "CURRENT" else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/nobrainer-skill-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nobrainer-skill-doctor
-description: "Use when the owner says nb-skill-doctor, requests a skill or task-prompt quality audit, or reviews instruction conflicts across projects. For which AGENTS files Codex loads in one project, use nobrainer-codex-context."
+description: "Use when the owner says nb-skill-doctor, requests a skill or task-prompt quality audit, or reviews instruction conflicts across projects. For which instruction files coding agents load in one project, use nobrainer-context."
 ---
 
 # NoBrainer Skill Doctor
@@ -105,8 +105,8 @@ their owner gate. A model/client behavior case that was not run is `UNTESTED`.
 
 ## Ownership boundaries
 
-- Use `nobrainer-codex-context` for one project's Codex instruction discovery,
-  context setup or repair.
+- Use `nobrainer-context` for one project's instruction files across coding
+  agents: discovery, consolidation or repair.
 - Use `nobrainer-review` for the exact diff, bug hunt or release closeout; the
   doctor does not replace its final evidence gate.
 - Use `nobrainer-build` for an accepted code, documentation or configuration fix.
@@ -123,7 +123,7 @@ review, capability installation or delivery orchestration.
 
 If repair is explicitly requested, freeze the source/ref and write only to the
 canonical target. Preserve user changes and managed blocks. Route context edits
-to `nobrainer-codex-context`, implementation edits to `nobrainer-build`, and a
+to `nobrainer-context`, implementation edits to `nobrainer-build`, and a
 consequential closeout to `nobrainer-review`. Do not silently change model
 selection, install a package, delete a skill, commit, push or publish.
 

package/skills/nobrainer-tech-flow/SKILL.md

@@ -42,9 +42,9 @@ Skip ledger, delegation, review and startup care. Escalate to the full Flow life
 for ambiguity, architecture, public behavior, routing or consequential
 side effects; quick path never bypasses an owner gate.
 
-For substantial work, delegate all independent ready units promptly through
-[team execution](references/delivery.md#coordinated-team-execution); MAIN coordinates,
-integrates, verifies and refills slots. Use [Auto Fine Tune](../nobrainer-auto-fine-tune/SKILL.md)
+Delegate aggressively: run substantial work's independent units
+on parallel native subagents through [team execution](references/delivery.md#coordinated-team-execution);
+MAIN integrates, verifies and refills slots. Use [Auto Fine Tune](../nobrainer-auto-fine-tune/SKILL.md)
 for first-setup capability checks; benchmark only when calibration pays.
 Unavailable native workers leave work in MAIN; visible conversations require explicit owner request
 or authorized MAIN restart; isolation, reuse or handoff alone never authorize one.

package/skills/nobrainer-tech-flow/VERSION

@@ -1 +1 @@
-2.4.1
+2.6.0

package/skills/nobrainer-tech-flow/references/daily-update.md

@@ -10,8 +10,11 @@ the client is current. A failed network check is `CHECK_FAILED`, not
 `CURRENT`.
 
 When `UPDATE_AVAILABLE`, tell the user the installed and latest version
-and the verified release link. Upgrade only within the owner's recorded
-standing authorization or after approval of the exact reviewed change.
+and the verified release link. The default instruction line ("Once a day on
+first use, update nobrainer-tech-flow...") authorizes this Flow-only upgrade to a
+verified stable release; the opt-out line ("tell the owner... do not update it
+yourself") does not. Otherwise upgrade only after approval of the exact reviewed
+change.
 Before applying, obtain the new release source at a verified immutable ref,
 compare installation targets, run `validate_skills.py --suite`, then dry-run
 `install_skills.py` and `install_personalization.py`. Preserve foreign

package/skills/nobrainer-tech-flow/references/delivery.md

@@ -115,6 +115,12 @@ useful authorized work remains. Never turn an unknown right/license into consent
 
 ## Keep review proportional to progress
 
+Scale verification to blast radius. A reversible, low-risk change 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.
+
 Review the next executable slice against concrete acceptance and failure paths.
 For a stable slice, default to one review and one focused correction verification.
 More review needs a newly evidenced material defect or changed risk, not a new
@@ -136,7 +142,14 @@ reviews, tests or generated files.
 ## Coordinated team execution
 
 MAIN owns the full outcome, coordination, critical path, dependencies, integration,
-owner decisions and acceptance. Before executing non-trivial work or entering a
+owner decisions and acceptance. Delegation is the default route to a faster done:
+MAIN works its own unit while workers run, and keeps only tiny, tightly coupled,
+gated or shared-state steps. Delegate a unit when it is independent and large
+enough that parallel work shortens the time to done more than a worker's start-up
+costs. Give each worker a short task packet, not the whole conversation, and ask
+for a concise report. Send narrow, mechanical work to a cheaper model under the
+host's policy. Each worker's model and effort come from that policy; the workflow
+names no model. Before executing non-trivial work or entering a
 blocking wait, identify independent ready units and dispatch every useful eligible
 unit promptly to native workers within verified host capacity and authorized usage
 limits. Eligibility requires accepted dependencies, authority, a supported route
@@ -197,7 +210,9 @@ worker completion, MAIN reconciles the exact returned ID, inspects the current
 artifact, assigned scope and required proof, and verifies that the worker has
 stopped writing. Then release only that unit's proven ownership, recompute readiness
 and dispatch newly ready work without waiting for unrelated slow workers. A
-worker's report, exit code or self-score does not accept its artifact.
+worker's report, exit code or self-score does not accept its artifact. When a batch
+partly fails, resend only the failed units with their new evidence; never rerun the
+accepted ones.
 
 A waiting, suspended or uncertain worker has a stated reason and a bounded next
 observation in the current tracker. Reserve its scope and possible capacity until

package/skills/nobrainer-tech-flow/references/optional-decisions.md

@@ -30,8 +30,10 @@ Jev/Laya records that preference in off mode until data/cost authority is known.
 `set` is an explicit configuration change. `show` never writes or uses a provider.
 Malformed config leaves its bytes intact, reports core fallback and does not
 re-open consent. `off` disables calls even with provider settings present.
-The configuration schema accepts no credential fields. Put the TypeSafe key in
-the invoking process's `TYPESAFE_API_KEY`; do not print it or put it in argv.
+The configuration schema accepts no credential fields. The helper reads no key
+from the machine unless you name the environment variable that holds it with
+`--key-env` (for example `--key-env TYPESAFE_API_KEY`); do not print the key or
+put its value in argv.
 
 ## Use bounded suggestions
 
@@ -53,7 +55,7 @@ a model. Example synthetic request:
 ```
 
 ```sh
-python3 <flow-skill-dir>/scripts/typed_decisions.py --request requests.json --approved-data
+python3 <flow-skill-dir>/scripts/typed_decisions.py --request requests.json --approved-data --key-env TYPESAFE_API_KEY
 ```
 
 `--approved-data` records existing scope authorization, not permission invented

package/skills/nobrainer-tech-flow/references/routing.md

@@ -9,7 +9,7 @@ trigger applies.
 | Need | Primary method |
 |---|---|
 | lifecycle, brief requirements, visible progress and guarded autonomy | `nobrainer-tech-flow` |
-| project-local Codex instruction discovery, byte-budget audit and context readback | `nobrainer-codex-context` |
+| one project's instruction files across coding agents: what loads, size, duplicates, contradictions, one source of truth | `nobrainer-context` |
 | cross-project instruction, skill and task-prompt audit with coverage planning | `nobrainer-skill-doctor` |
 | capability selection, bounded native assignments or open-skill evaluation | `nobrainer-team` |
 | ready-set calculation, dependency batches, bounded dispatch and backpressure | `nobrainer-dispatcher` |

package/skills/nobrainer-tech-flow/scripts/typed_decisions.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 """Bounded advisory typed decisions; never executes selected actions."""
 import argparse
+import functools
 import json
 import math
 import os
@@ -81,9 +82,8 @@ class NoRedirect(urllib.request.HTTPRedirectHandler):
         raise ValueError("redirect_not_allowed")
 
 
-def worker(provider, model, request):
+def worker(provider, model, request, key=None):
     if provider == "jev":
-        key = os.environ.get("TYPESAFE_API_KEY")
         if not key:
             return {"error": "MISSING_TYPESAFE_API_KEY"}
         payload = json.dumps(dict(request, model=model)).encode()
@@ -123,13 +123,19 @@ def worker(provider, model, request):
     return result
 
 
-def invoke(provider, model, request, timeout):
+def invoke(provider, model, request, timeout, key_env=None):
+    # The child gets no credential from the environment. The TypeSafe key is read only
+    # from the variable the caller names with --key-env, and passed on stdin.
     env = {k: v for k, v in os.environ.items()
            if not any(part in k.upper() for part in ("KEY", "TOKEN", "SECRET", "PASSWORD", "CREDENTIAL"))}
-    if provider == "jev" and os.environ.get("TYPESAFE_API_KEY"):
-        env["TYPESAFE_API_KEY"] = os.environ["TYPESAFE_API_KEY"]
+    if key_env:
+        # The named variable may not look like a credential (TYPESAFE_AUTH, FOO); drop it anyway.
+        # Windows treats variable names without regard to case.
+        for name in [k for k in env if k == key_env or (os.name == "nt" and k.upper() == key_env.upper())]:
+            del env[name]
+    key = os.environ.get(key_env) if provider == "jev" and key_env else None
     process = subprocess.run([sys.executable, str(Path(__file__).resolve()), "--worker", provider, model],
-                             input=json.dumps(request), capture_output=True, text=True,
+                             input=json.dumps({"request": request, "key": key}), capture_output=True, text=True,
                              timeout=timeout, env=env)
     if process.returncode:
         raise ValueError("provider_failed")
@@ -182,9 +188,11 @@ def main():
             # Third-party stdout may contain progress or input; contain it.
             import contextlib
             import io
-            request = validate_request(json.load(sys.stdin))
+            payload = json.load(sys.stdin)
+            request = validate_request(payload["request"])
+            key = payload.get("key") if isinstance(payload.get("key"), str) else None
             with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
-                result = worker(sys.argv[2], sys.argv[3], request)
+                result = worker(sys.argv[2], sys.argv[3], request, key)
             print(json.dumps(result))
             return 0
         except Exception:
@@ -194,12 +202,15 @@ def main():
     parser.add_argument("--config", type=Path, default=Path(".nobrainer/flow.json"))
     parser.add_argument("--request", type=Path, help="JSON array of requests; otherwise stdin")
     parser.add_argument("--approved-data", action="store_true", help="Only with existing approval for this data and provider")
+    parser.add_argument("--key-env", metavar="NAME",
+                        help="Jev only: the environment variable that holds your TypeSafe key; nothing is read without it")
     args = parser.parse_args()
     try:
         data = json.loads(args.request.read_text()) if args.request else json.load(sys.stdin)
         if not isinstance(data, list) or len(data) > 100:
             raise ValueError("batch")
-        print(json.dumps(evaluate(data, read(args.config), args.approved_data), ensure_ascii=False))
+        call = functools.partial(invoke, key_env=args.key_env)
+        print(json.dumps(evaluate(data, read(args.config), args.approved_data, call), ensure_ascii=False))
         return 0
     except (OSError, ValueError, TypeError):
         print(json.dumps({"status": "CORE_FALLBACK", "reason": "INVALID_INPUT"}))