nobrainer-tech-flow 0.0.0-stage → 2.4.0

package/scripts/validate_skills.py

@@ -0,0 +1,465 @@
+#!/usr/bin/env python3
+"""Validate portable skill structure and the NoBrainer canonical suite."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SKILLS = ROOT / "skills"
+NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+MAX_NAME_LENGTH = 64
+LINK_RE = re.compile(r"\[[^\]]+\]\((?!https?://|#|mailto:)([^)]+)\)")
+
+SUITE = {
+    "nobrainer-auto-fine-tune": "nb-auto-fine-tune",
+    "nobrainer-codex-context": "nb-codex-context",
+    "nobrainer-skill-doctor": "nb-skill-doctor",
+    "nobrainer-tech-flow": "NBFlow",
+    "nobrainer-team": "nb-team",
+    "nobrainer-dispatcher": "nb-dispatcher",
+    "nobrainer-research": "nb-research",
+    "nobrainer-writing": "nb-write",
+    "nobrainer-build": "nb-build",
+    "nobrainer-security": "nb-security",
+    "nobrainer-sessions": "nb-sessions",
+    "nobrainer-spec-driven-development": "nb-sdd",
+    "nobrainer-wiki": "nb-wiki",
+    "nobrainer-browser": "nb-browser",
+    "nobrainer-autoimprove": "nb-autoimprove",
+    "nobrainer-decide": "nb-decide",
+    "nobrainer-rca": "nb-rca",
+    "nobrainer-review": "nb-review",
+}
+REQUIRED_ALIASES = {
+    "nobrainer-tech-flow": ("NBFlow", "NBF", "nobrainer-tech-flow"),
+}
+
+LEGACY = {
+    "nobrainer-ultra",
+    "add-gitleaks",
+    "agent-browser",
+    "agents-restraint",
+    "codex-in-claude-code",
+    "code-autoresearch",
+    "deep-audit",
+    "deep-autoreview",
+    "deep-autoresearch",
+    "deep-bugs-finder",
+    "deep-code-review",
+    "deep-decide",
+    "dispatching-parallel-agents",
+    "deep-rca",
+    "engineering-standards",
+    "karpathy-auto-improver",
+    "karpathy-llm-wiki",
+    "llm-wiki",
+    "nb-add",
+    "nb-flow",
+    "nb-dispatcher",
+    "nb-get",
+    "nb-multi",
+    "nb-tidy",
+    "nb-workflow",
+    "nb-write",
+    "nobrainer-autopilot",
+    "nobrainer-capture-lesson",
+    "nobrainer-continuous-improvement",
+    "nobrainer-memory",
+    "nobrainer-memory-memsearch",
+    "nobrainer-npm-secure",
+    "nobrainer-reddit",
+    "nobrainer-starter",
+    "nobrainer-skill-browser",
+    "nobrainer-simplifier",
+    "nobrainer-style",
+    "nobrainer-human-like",
+    "security-review",
+    "session-handoff",
+    "nobrainer-team-builder",
+    "nobrainer-ultracode-workflow",
+    "nobrainer-wiki-add",
+    "nobrainer-wiki-get",
+    "nobrainer-wiki-tidy",
+    "playwright-cli",
+    "wiki-add",
+    "wiki-get",
+    "wiki-tidy",
+}
+
+ACTIVE = set(SUITE)
+
+PUBLIC_FORBIDDEN = (
+    "/Users/",
+    "/opt/homebrew/",
+    "/private/tmp/",
+    "nobrainer-tech@",
+    "--dangerously-skip-permissions",
+    "CLAUDE-CODE-FABLE",
+)
+EXTERNAL_WORKFLOW_BRANDS = (
+    "av" + "thar",
+    "ti" + "bo",
+    "super" + "powers",
+)
+PORTABLE_FRONTMATTER = {"name", "description"}
+PUBLIC_TEXT_SUFFIXES = {
+    ".json",
+    ".js",
+    ".md",
+    ".ps1",
+    ".py",
+    ".sh",
+    ".svg",
+    ".toml",
+    ".yaml",
+    ".yml",
+}
+PUBLIC_EXTENSIONLESS_FILES = {
+    ROOT / "hooks" / "run-hook.cmd",
+    ROOT / "hooks" / "session-start",
+}
+PUBLIC_ROOT_FILES = (
+    ROOT / ".gitattributes",
+    ROOT / ".gitleaks.toml",
+    ROOT / ".gitignore",
+    ROOT / ".pre-commit-config.yaml",
+    ROOT / "README.md",
+    ROOT / "RELEASE-NOTES.md",
+    ROOT / "AGENTS.md",
+    ROOT / "CLAUDE.md",
+    ROOT / "CONTRIBUTING.md",
+    ROOT / "GEMINI.md",
+    ROOT / "LICENSE",
+    ROOT / "SECURITY.md",
+    ROOT / "gemini-extension.json",
+    ROOT / "plugin.json",
+    ROOT / "package.json",
+)
+PUBLIC_ROOT_DIRS = (
+    ROOT / "docs",
+    ROOT / "assets",
+    ROOT / ".agents",
+    ROOT / ".claude-plugin",
+    ROOT / ".codex-plugin",
+    ROOT / ".cursor-plugin",
+    ROOT / ".github",
+    ROOT / ".kimi-plugin",
+    ROOT / ".opencode",
+    ROOT / ".pi",
+    ROOT / "adapters",
+    ROOT / "hooks",
+    ROOT / "scripts",
+    ROOT / "tests",
+)
+DETECTOR_FIXTURE_FILES = {
+    ROOT / "scripts" / "validate_skills.py",
+    ROOT / "tests" / "test_suite.py",
+}
+VERSION_PATHS = (
+    ROOT / "package.json",
+    ROOT / "plugin.json",
+    ROOT / ".claude-plugin" / "plugin.json",
+    ROOT / ".codex-plugin" / "plugin.json",
+    ROOT / ".cursor-plugin" / "plugin.json",
+    ROOT / ".kimi-plugin" / "plugin.json",
+    ROOT / "gemini-extension.json",
+)
+FROZEN_EVAL_PAYLOAD_SUFFIXES = (
+    "-prompt.md",
+    "-output.md",
+    "-judge.md",
+    "-judge-rubric.md",
+)
+
+
+def parse_frontmatter(path: Path) -> tuple[dict[str, str], str]:
+    text = path.read_text(encoding="utf-8")
+    lines = text.splitlines()
+    if not lines or lines[0] != "---":
+        raise ValueError("frontmatter must start on line 1")
+    try:
+        end = lines.index("---", 1)
+    except ValueError as exc:
+        raise ValueError("frontmatter is not closed") from exc
+
+    values: dict[str, str] = {}
+    key: str | None = None
+    chunks: list[str] = []
+    for line in lines[1:end]:
+        match = re.match(r"^([a-zA-Z0-9_-]+):(?:\s*(.*))?$", line)
+        if match:
+            if key is not None:
+                values[key] = " ".join(chunks).strip().strip('"')
+            key = match.group(1)
+            raw = (match.group(2) or "").strip()
+            chunks = [] if raw in {"", ">", ">-", "|", "|-"} else [raw]
+        elif key is not None and line.startswith("  "):
+            chunks.append(line.strip())
+        elif line.strip():
+            raise ValueError(f"unsupported frontmatter line: {line}")
+    if key is not None:
+        values[key] = " ".join(chunks).strip().strip('"')
+    return values, text
+
+
+def active_skill_files() -> list[Path]:
+    return sorted(SKILLS.glob("*/SKILL.md"))
+
+
+def is_public_text_file(path: Path) -> bool:
+    return path.is_file() and (
+        path.suffix.lower() in PUBLIC_TEXT_SUFFIXES
+        or path in PUBLIC_EXTENSIONLESS_FILES
+    )
+
+
+def public_text_files() -> list[Path]:
+    paths = {path for path in PUBLIC_ROOT_FILES if path.is_file()}
+    for directory in PUBLIC_ROOT_DIRS:
+        if not directory.is_dir():
+            continue
+        paths.update(
+            path
+            for path in directory.rglob("*")
+            if is_public_text_file(path)
+        )
+    for skill in active_skill_files():
+        paths.update(
+            path
+            for path in skill.parent.rglob("*")
+            if is_public_text_file(path)
+        )
+    return sorted(paths)
+
+
+def relative_link_errors(path: Path, text: str) -> list[str]:
+    errors: list[str] = []
+    for match in LINK_RE.finditer(text):
+        target = match.group(1).split("#", 1)[0]
+        if not target or target.startswith("/") or "$" in target:
+            continue
+        if not (path.parent / target).resolve().exists():
+            errors.append(f"{path.relative_to(ROOT)}: broken relative link {target}")
+    return errors
+
+
+def should_validate_relative_links(path: Path) -> bool:
+    """Skip literal Markdown copied into immutable model-evaluation payloads."""
+    artifact_dir = ROOT / "docs" / "evals" / "artifacts"
+    return not (
+        path.parent == artifact_dir
+        and path.name.endswith(FROZEN_EVAL_PAYLOAD_SUFFIXES)
+    )
+
+
+def public_scan_text(path: Path, text: str) -> str:
+    """Remove the one intentional detector fixture, but scan every other use."""
+    if path not in DETECTOR_FIXTURE_FILES:
+        return text
+    indent = "            " if path.name == "test_suite.py" else "    "
+    for forbidden in PUBLIC_FORBIDDEN:
+        fixture = f'{indent}"{forbidden}",'
+        if text.count(fixture) != 1:
+            return text
+        text = text.replace(fixture, "", 1)
+    return text
+
+
+def validate(suite_only: bool) -> list[str]:
+    errors: list[str] = []
+    seen: dict[str, Path] = {}
+
+    for path in active_skill_files():
+        try:
+            frontmatter, text = parse_frontmatter(path)
+        except ValueError as exc:
+            errors.append(f"{path.relative_to(ROOT)}: {exc}")
+            continue
+        name = frontmatter.get("name", "")
+        description = frontmatter.get("description", "")
+        extra_keys = set(frontmatter) - PORTABLE_FRONTMATTER
+        if extra_keys:
+            errors.append(
+                f"{path.relative_to(ROOT)}: non-portable frontmatter keys "
+                f"{', '.join(sorted(extra_keys))}"
+            )
+        if not NAME_RE.fullmatch(name):
+            errors.append(f"{path.relative_to(ROOT)}: invalid name {name!r}")
+        if len(name) > MAX_NAME_LENGTH:
+            errors.append(
+                f"{path.relative_to(ROOT)}: invalid name length "
+                f"{len(name)} > {MAX_NAME_LENGTH}"
+            )
+        if name != path.parent.name:
+            errors.append(
+                f"{path.relative_to(ROOT)}: name {name!r} does not match directory"
+            )
+        if not description or len(description) > 1024:
+            errors.append(f"{path.relative_to(ROOT)}: invalid description length")
+        if name in seen:
+            errors.append(
+                f"duplicate name {name!r}: {seen[name].relative_to(ROOT)} and "
+                f"{path.relative_to(ROOT)}"
+            )
+        seen[name] = path
+        errors.extend(relative_link_errors(path, text))
+
+    if not suite_only:
+        return errors
+
+    active_names = {path.parent.name for path in active_skill_files()}
+    if active_names != ACTIVE:
+        missing = sorted(ACTIVE - active_names)
+        extra = sorted(active_names - ACTIVE)
+        errors.append(f"active inventory mismatch: missing={missing}, extra={extra}")
+
+    for name, alias in SUITE.items():
+        path = SKILLS / name / "SKILL.md"
+        if not path.is_file():
+            errors.append(f"missing canonical skill {name}")
+            continue
+        try:
+            frontmatter, _ = parse_frontmatter(path)
+        except ValueError as exc:
+            errors.append(f"{path.relative_to(ROOT)}: {exc}")
+            continue
+        if set(frontmatter) != PORTABLE_FRONTMATTER:
+            errors.append(f"{path.relative_to(ROOT)}: suite frontmatter must contain only name and description")
+        if not frontmatter.get("description", "").startswith("Use when"):
+            errors.append(f"{path.relative_to(ROOT)}: description must start with 'Use when'")
+        if alias not in frontmatter.get("description", ""):
+            errors.append(f"{path.relative_to(ROOT)}: missing alias trigger {alias}")
+        for required_alias in REQUIRED_ALIASES.get(name, ()):
+            if required_alias not in frontmatter.get("description", ""):
+                errors.append(
+                    f"{path.relative_to(ROOT)}: missing required alias trigger {required_alias}"
+                )
+    for name in LEGACY:
+        if (SKILLS / name / "SKILL.md").exists():
+            errors.append(f"legacy skill remains discoverable: {name}")
+
+    for path in public_text_files():
+        text = path.read_text(encoding="utf-8")
+        scanned_text = public_scan_text(path, text)
+        for forbidden in PUBLIC_FORBIDDEN:
+            if forbidden in scanned_text:
+                errors.append(
+                    f"{path.relative_to(ROOT)}: forbidden public value {forbidden!r}"
+                )
+        for brand in EXTERNAL_WORKFLOW_BRANDS:
+            # Dated review reports may attribute outside projects. Operational
+            # instructions retain the branding gate; public-value scanning above
+            # still applies to every report.
+            is_review_document = (
+                path.parent == ROOT / "docs" / "reviews"
+                and path.suffix.lower() == ".md"
+            )
+            if brand in text.lower() and not is_review_document:
+                errors.append(
+                    f"{path.relative_to(ROOT)}: external workflow branding {brand!r}"
+                )
+        if (
+            path.suffix.lower() == ".md"
+            and path.name != "SKILL.md"
+            and should_validate_relative_links(path)
+        ):
+            errors.extend(relative_link_errors(path, text))
+
+    versions: dict[str, str] = {}
+    for path in VERSION_PATHS:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            errors.append(f"{path.relative_to(ROOT)}: invalid version manifest: {exc}")
+            continue
+        version = data.get("version")
+        if not isinstance(version, str) or not version:
+            errors.append(f"{path.relative_to(ROOT)}: missing version")
+            continue
+        versions[str(path.relative_to(ROOT))] = version
+
+    marketplace = ROOT / ".claude-plugin" / "marketplace.json"
+    try:
+        data = json.loads(marketplace.read_text(encoding="utf-8"))
+        versions[str(marketplace.relative_to(ROOT))] = data["plugins"][0]["version"]
+    except (OSError, json.JSONDecodeError, KeyError, IndexError, TypeError) as exc:
+        errors.append(f"{marketplace.relative_to(ROOT)}: invalid plugin version: {exc}")
+
+    other_versions, other_errors = release_version_sources(ROOT)
+    versions.update(other_versions)
+    errors.extend(other_errors)
+
+    if len(set(versions.values())) > 1:
+        errors.append(f"manifest version mismatch: {versions}")
+
+    codex_manifest = ROOT / ".codex-plugin" / "plugin.json"
+    try:
+        codex_data = json.loads(codex_manifest.read_text(encoding="utf-8"))
+        if "hooks" in codex_data:
+            errors.append(
+                f"{codex_manifest.relative_to(ROOT)}: hooks must be omitted; "
+                "Claude hooks use an explicit non-default path so Codex cannot "
+                "auto-discover them"
+            )
+        if (ROOT / "hooks" / "hooks.json").exists():
+            errors.append(
+                "hooks/hooks.json: reserved Codex auto-discovery path must remain "
+                "absent; use a client-specific hook path"
+            )
+        if codex_data.get("skills") != "./skills/":
+            errors.append(f"{codex_manifest.relative_to(ROOT)}: skills path must be ./skills/")
+    except (OSError, json.JSONDecodeError, TypeError) as exc:
+        errors.append(f"{codex_manifest.relative_to(ROOT)}: invalid Codex manifest: {exc}")
+
+    return errors
+
+
+def release_version_sources(root: Path) -> tuple[dict[str, str], list[str]]:
+    """Versions kept outside the plugin manifests.
+
+    The skill's VERSION file is what the update check compares with the latest
+    release, and the npm lockfile repeats the package version twice; both have to
+    move with the manifests or users see a false or missing update.
+    """
+
+    versions: dict[str, str] = {}
+    errors: list[str] = []
+    version_file = root / "skills" / "nobrainer-tech-flow" / "VERSION"
+    try:
+        versions["skills/nobrainer-tech-flow/VERSION"] = version_file.read_text(
+            encoding="utf-8"
+        ).strip()
+    except OSError as exc:
+        errors.append(f"skills/nobrainer-tech-flow/VERSION: unreadable: {exc}")
+    lockfile = root / "package-lock.json"
+    try:
+        data = json.loads(lockfile.read_text(encoding="utf-8"))
+        versions["package-lock.json"] = data["version"]
+        versions['package-lock.json packages[""]'] = data["packages"][""]["version"]
+    except (OSError, json.JSONDecodeError, KeyError, TypeError) as exc:
+        errors.append(f"package-lock.json: invalid version fields: {exc}")
+    return versions, errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--suite", action="store_true", help="enforce canonical suite gates")
+    args = parser.parse_args()
+    errors = validate(args.suite)
+    if errors:
+        for error in errors:
+            print(f"ERROR: {error}")
+        return 1
+    scope = "canonical suite" if args.suite else "active skills"
+    print(f"OK: validated {scope}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/nobrainer-auto-fine-tune/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: nobrainer-auto-fine-tune
+description: "Use when setting up nobrainer-tech-flow for the first time, when the owner says nb-auto-fine-tune, or when client capabilities, model routing, context or useful parallelism need recalibration."
+---
+
+# nobrainer-tech-flow: Orchestration Calibration
+
+Run this skill as the standard first-setup step for nobrainer-tech-flow. Discover the current client's and project's actual capabilities, calibrate supported worker routes when useful, and record evidence-backed recommendations. Ordinary delegation follows [team execution](../nobrainer-tech-flow/references/delivery.md#coordinated-team-execution); calibration is not a prerequisite to dispatch. Read [capacity and update audit](references/capacity-audit.md) at project setup or when limits are in question. It does not train or fine-tune model weights, choose a replacement for MAIN, create sessions, schedule workers, or run an open-ended optimization loop.
+
+## Preserve the owner's choice
+
+Treat the model and effort selected for MAIN as fixed for this task. Do not lower or replace them to save cost. Recommend separate worker models and effort only for bounded delegated work, using currently available evidence. If the selected MAIN identity or effort is not observable, preserve the current runtime and report `UNKNOWN`; do not infer it from a saved preference, prior task, or model catalog.
+
+## Discover this client's actual capabilities
+
+Inspect the current harness and relevant project/client configuration for:
+
+- models and exact model identifiers the client advertises;
+- models and effort levels the current runtime can actually request;
+- native subagent creation, isolated worktrees, concurrency limits, and available transport/readback;
+- active client version/update status; effective profile, selected provider, configured versus catalog-advertised versus observed context window;
+- any trustworthy latency, token, or cost telemetry and its measurement scope.
+
+Keep advertised, configured, callable, and successfully invoked capabilities distinct. Verify a capability with a read-only or harmless probe only when supported and useful. Never make a paid benchmark call merely to prove a model exists. Record unavailable, hidden, or unverified fields as `UNKNOWN` or `UNSUPPORTED`. Do not hardcode model names, rankings, prices, concurrency, or provider behavior. A model name suggested in a prompt is not proof that the host honored it.
+
+## Decide whether calibration is worth doing
+
+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.
+
+## Run a bounded, comparable calibration
+
+Before comparing worker routes, freeze:
+
+- the task category and representative cases, including an ordinary case and a relevant edge or non-trigger case;
+- identical inputs, instructions, tools, output contract, and acceptance rubric for each candidate;
+- the quality gates and any minimum acceptable score;
+- the latency measurement boundary, such as request-to-complete, and the available cost/token source;
+- a small call and time budget, retry rule, and stop condition.
+
+Run candidates on the same cases. Blind or shuffle outputs for subjective review when practical. Score acceptance and factuality first; then compare measured latency and cost among routes that meet quality gates. Use repeated paired trials only when variability could change the routing decision and budget allows. Do not fabricate costs from public list prices, estimate latency from model labels, cherry-pick retries, or treat a worker's self-report as independent evaluation. If telemetry is absent, report that dimension as `UNMEASURED`.
+
+Stop when evidence identifies an adequate route, the result is inconclusive, the budget is reached, or a quality/safety gate fails. Return `NO_CHANGE` when no candidate demonstrates a useful improvement. Calibration evidence applies only to the tested client, task category, settings, and period; it is not a universal model ranking.
+
+## Produce a routing policy
+
+Return a concise policy with:
+
+```text
+CLIENT_AND_RUNTIME:
+MAIN_MODEL_AND_EFFORT: PRESERVED | UNKNOWN
+CAPABILITIES: ADVERTISED / CONFIGURED / CALLABLE / VERIFIED, with exact IDs and evidence
+TASK_CATEGORY_AND_CASES:
+CANDIDATE_ROUTES_AND_SETTINGS:
+QUALITY_RESULT:
+LATENCY_RESULT: measured boundary and result | UNMEASURED
+COST_OR_TOKEN_RESULT: source and result | UNMEASURED
+PARALLELISM: useful slots, dependencies, write isolation, integration cost | UNKNOWN where unverified
+CONTEXT: configured / catalog-advertised / provider-documented / runtime-observed
+CLIENT_UPDATE: UP_TO_DATE | AVAILABLE | BUSY | UNAVAILABLE | UNKNOWN
+RECOMMENDATION: route by task category; retain MAIN choice
+LIMITS_AND_EXPIRY:
+PERSONALIZATION_CHANGE: NOT_PROPOSED | PREPARED_FOR_REVIEW | APPLIED_WITH_EXPLICIT_AUTHORIZATION
+```
+
+State the next calibration trigger, such as a runtime/model catalog change, a material quality regression, or a changed workload. Do not retain secrets or unnecessary user data in the policy.
+
+## Keep the Flow skill boundaries
+
+- `nobrainer-team` owns capability-to-role design and assignment contracts. Give it this skill's verified candidate evidence; do not duplicate its roster planning.
+- `nobrainer-dispatcher` owns ready-set selection, batch ordering, and backpressure. Give it measured concurrency and critical-path findings; do not dispatch workers here.
+- `nobrainer-sessions` owns visible session identity, transport, restart, archive, leases, and receive-audit. Recommend a restart or archival only through its lifecycle rules and current authorization; this skill never creates, restarts, or archives a session.
+- `nobrainer-autoimprove` owns frozen baseline/candidate/holdout experiments for changing prompts, skills, or durable artifacts. Route artifact tuning there; this skill may provide the routing benchmark contract but does not tune its own rubric or promote a candidate.
+- The user owns persistent client/global personalization. Discover the appropriate documented settings surface and use the existing authorization for Flow setup when it covers that surface. Preview the smallest exact change, preserve unrelated instructions, make a recoverable backup, and verify the saved value by readback. If the scope is not authorized or materially ambiguous, ask for that decision. Prefer the client's global instruction surface for portable Flow awareness and a project instruction file for project-specific choices; never claim one client setting applies to another tool. Reuse the managed personalization installer rather than writing an untracked second configuration path.
+
+## Closeout
+
+Report the exact capabilities verified, the comparison performed or why it was skipped, measured results versus unknowns, the recommended task-specific routing, whether any setting was changed, and the next evidence needed. A configured preference, model listing, queued task, or worker report alone does not prove a callable or better route.

package/skills/nobrainer-auto-fine-tune/references/capacity-audit.md

@@ -0,0 +1,49 @@
+# Client capacity and update audit
+
+Use this on first project setup, after a client/model update, or when a
+measured task repeatedly hits a context or worker ceiling. Start read-only.
+
+## Separate four evidence layers
+
+Record the running client/version, selected MAIN model and effort, effective
+profile/provider, and source of each value. For context, keep
+`CONFIGURED_LIMIT`, `CATALOG_ADVERTISED_LIMIT`,
+`PROVIDER_DOCUMENTED_LIMIT` and `RUNTIME_OBSERVED` separate. A larger model
+card or API window does not prove that the client grants it. Do not promote
+a claimed million-token window or a proposed 872,000-token setting into a
+verified runtime fact.
+
+For workers, record native spawn support, exact model IDs, per-worker effort
+support, configured concurrency, actual successful concurrent launches,
+current running workers and practical integration cost. A config value such
+as 15 is a ceiling, not observed capacity. Use ordinary useful work to test
+capacity; do not create filler probes or exceed host restrictions.
+
+Check whether the running client has an eligible update through its native
+version/status channel when available. Treat `AVAILABLE`, `UP_TO_DATE`,
+`BUSY`, `UNAVAILABLE` and `UNKNOWN` as different outcomes. Do not equate
+Flow's daily release check with a client-app update. Never download or restart
+a user's app from a read-only check.
+
+## Client adapters
+
+- **Codex:** inspect the selected profile as well as base config, local model
+  catalog, effective session status, worker configuration and native app update
+  status. The optional [NoBrainer Codex](https://github.com/nobrainer-tech/nobrainer-codex)
+  installer can provide a Codex-specific `install.py --check` preflight.
+  It is a separate product; its planned setting is not runtime proof.
+- **Claude Code:** inspect available subagent models, effort and capacity from
+  the active client and its current settings. A named model file or allowlist
+  is not proof that the worker actually ran on that model.
+- **OpenCode and other clients:** inspect their effective model/provider
+  selection, agents and plugin settings through supported native means. A
+  lightweight default or title-generation model is not automatically an
+  eligible task worker.
+
+Recommend a larger context or worker ceiling only when the active model,
+provider and client all support the exact value and a real task benefits.
+Prepare the smallest settings diff and rollback. Apply only within the
+owner's authorization and client-supported mechanism, then read back the
+saved value, selected MAIN model/effort and a representative runtime task.
+If effective settings or actual runtime capacity cannot be observed, report
+`CONFIGURED_ONLY` or `UNKNOWN` rather than claiming improvement.