diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..24dbf42 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,108 @@ +name: CI + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +concurrency: + group: ci-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + validate: + name: CI Gate + runs-on: ubuntu-latest + timeout-minutes: 10 + + steps: + - name: Check out repository + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0 + with: + python-version: "3.13" + + - name: Install JSON Schema validator + run: python -m pip install --disable-pip-version-check jsonschema==4.26.0 + + - name: Validate JSON and packet fixtures + run: | + python - <<'PY' + import json + from pathlib import Path + + from jsonschema import Draft202012Validator, FormatChecker + + root = Path(".") + json_paths = sorted(root.rglob("*.json")) + for path in json_paths: + json.loads(path.read_text(encoding="utf-8")) + + schema_path = Path("schemas/research-source-packets-v0.1.json") + schema = json.loads(schema_path.read_text(encoding="utf-8")) + Draft202012Validator.check_schema(schema) + validator = Draft202012Validator( + schema, + format_checker=FormatChecker(), + ) + + valid_paths = sorted(Path("fixtures/valid").glob("*.json")) + valid_paths += sorted(Path("examples").glob("*.json")) + for path in valid_paths: + payload = json.loads(path.read_text(encoding="utf-8")) + errors = sorted( + validator.iter_errors(payload), + key=lambda error: list(error.absolute_path), + ) + if errors: + raise SystemExit(f"{path}: {errors[0].message}") + + invalid_paths = sorted(Path("fixtures/invalid").glob("*.json")) + for path in invalid_paths: + payload = json.loads(path.read_text(encoding="utf-8")) + if not list(validator.iter_errors(payload)): + raise SystemExit(f"{path}: expected schema rejection") + + print( + f"Validated {len(json_paths)} JSON files, " + f"{len(valid_paths)} valid packets, and " + f"{len(invalid_paths)} invalid fixtures." + ) + PY + + - name: Lint changed Markdown + env: + BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }} + HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }} + run: | + files=() + if [[ ! "$BASE_SHA" =~ ^0+$ ]] && \ + git cat-file -e "$BASE_SHA^{commit}" 2>/dev/null; then + while IFS= read -r -d '' file; do + files+=("$file") + done < <( + git diff --name-only --diff-filter=ACMR -z \ + "$BASE_SHA" "$HEAD_SHA" -- '*.md' + ) + else + while IFS= read -r -d '' file; do + files+=("$file") + done < <(git ls-files -z '*.md') + fi + + if (( ${#files[@]} == 0 )); then + echo "No Markdown files changed." + exit 0 + fi + + printf 'Linting %s\n' "${files[@]}" + npx --yes markdownlint-cli2@0.23.0 "${files[@]}" diff --git a/docs/openai-codex-reasoning-levels-2026-07-13.md b/docs/openai-codex-reasoning-levels-2026-07-13.md new file mode 100644 index 0000000..53f009b --- /dev/null +++ b/docs/openai-codex-reasoning-levels-2026-07-13.md @@ -0,0 +1,281 @@ +# OpenAI Codex Reasoning Levels: Operational Definitions + +Status: candidate research note. This document records current product wording +and an evidence-bounded interpretation; it does not create HUMMBL canon. + +Date: July 13, 2026. + +Review status: revised after independent ChatGPT review on July 13, 2026. + +## Research question + +What does OpenAI mean when Codex describes reasoning levels as Low, Medium, +High, Extra High, Max, and Ultra? + +## Short answer + +A reasoning level controls how much internal computational effort the selected +model may spend analyzing, planning, exploring alternatives, checking +assumptions, and verifying work before responding. + +Low through Max do not select a different base model. They are relative effort +controls for the selected model. Higher settings generally trade more response +time and usage for a better chance of solving difficult problems well. They do +not guarantee correctness or prescribe a fixed amount of time or tokens. + +The progression is: + +`Low -> Medium -> High -> Extra High -> Max` + +These levels progressively increase reasoning effort applied to the selected +model. They do not proactively delegate merely because of the level, although +the user can explicitly request subagents at non-Ultra levels. `Ultra` is +structurally different: it combines maximum reasoning with permission to +delegate suitable work proactively. + +## Observed Codex selector context + +The operator supplied a Codex CLI transcript from July 13, 2026. The installed +CLI version was independently verified as `codex-cli 0.144.3` on Anvil. + +The observed model selector listed: + +- `gpt-5.6-sol`: "Latest frontier agentic coding model." +- `gpt-5.6-terra`: "Balanced agentic coding model for everyday work." +- `gpt-5.6-luna`: "Fast and affordable agentic coding model." +- `gpt-5.5`: "Frontier model for complex coding, research, and real-world + work." +- `gpt-5.4`: "Strong model for everyday coding." +- `gpt-5.4-mini`: "Small, fast, and cost-efficient model for simpler coding + tasks." +- `gpt-5.3-codex-spark`: "Ultra-fast coding model." + +For `gpt-5.6-sol`, the observed reasoning selector listed: + +- Low: "Fast responses with lighter reasoning." +- Medium: "Balances speed and reasoning depth for everyday tasks." +- High: "Greater reasoning depth for complex problems." +- Extra High: "Extra high reasoning depth for complex problems." +- Max: "For difficult problems when quality matters more than speed; higher + usage." +- Ultra: "For demanding work using multiple agents; highest usage." + +This transcript is an observation of the product surface, not a specification +of numerical compute, latency, or token limits. + +## Surface terminology + +OpenAI uses related but non-identical terminology across surfaces: + +- The Codex CLI uses **Low**, while the Codex app, ChatGPT Work, and IDE + extension may label the corresponding setting **Light**. +- The app and CLI expose product-facing levels such as Medium, High, Extra + High, Max, and Ultra when supported by the selected model and account. +- API `reasoning.effort` values are model-dependent. They can include `none`, + `minimal`, `low`, `medium`, `high`, and `xhigh`; GPT-5.6 also supports `max`. +- **Extra High** is the product-facing label associated with `xhigh`. +- **Ultra** is a Codex or ChatGPT orchestration mode, not merely another + ordinary API reasoning-effort value. + +Medium was the observed default for `gpt-5.6-sol` in the supplied selector. +Defaults remain model-dependent and should not be generalized universally. + +## Definition of reasoning effort + +OpenAI documents `reasoning.effort` as guidance to the model about how much to +think while performing a task. Lower effort favors speed and lower token use; +higher effort allows more complete reasoning and can improve response quality. +Reasoning remains adaptive: a model may use less effort for a simple task and +more for a complex one, even at the same configured level. + +Supported values and defaults are model-dependent. The labels therefore +describe relative operating points, not universal or directly comparable +quantities across every model generation. + +Reasoning effort should not be confused with: + +- **Model choice:** Sol, Terra, Luna, and other models have different baseline + capability, speed, and cost profiles. +- **Response length:** higher reasoning effort does not necessarily produce a + longer visible answer. GPT-5.6 exposes response detail separately through + `text.verbosity` in the API. +- **Context capacity:** changing effort does not itself expand the model's + context window. +- **Permissions or tools:** effort does not grant filesystem, network, or + connector access. +- **Correctness:** more reasoning can improve difficult-task performance, but + no level guarantees a correct result. + +## Operational definition by level + +### Low + +"Fast responses with lighter reasoning" means Codex prioritizes latency and +efficiency over extensive deliberation. It can still plan and use tools, but it +is less strongly encouraged to explore alternatives or perform deep checking. + +Use Low for clear, well-scoped tasks, routine transformations, simple edits, +fast information retrieval, or execution where the desired result is already +well specified. + +### Medium + +"Balances speed and reasoning depth" means Codex receives a moderate reasoning +allowance intended to sit near the practical balance among latency, quality, +reliability, and usage. OpenAI presents Medium as the normal starting point for +most agentic work. + +Use Medium for everyday coding, research, tool use, planning, document work, +and tasks that require judgment but are not unusually difficult. + +### High + +"Greater reasoning depth" means Codex is encouraged to spend more effort +tracing complex logic, checking assumptions, considering edge cases, and +planning or validating multiple steps. Quality is prioritized more heavily +than response speed. + +Use High for complex debugging, architecture, consequential review, +long-horizon research, ambiguous multi-step implementation, or work where +missed edge cases are expensive. + +### Extra High (`xhigh`) + +"Extra high reasoning depth" means a larger reasoning-effort setting for +especially challenging or long-running tasks. OpenAI associates `xhigh` with +deep research, asynchronous agentic work, security and code review, and +challenging coding workflows. + +Extra High does not proactively delegate merely because of the level. It also +does not prohibit subagents: the user can explicitly request them at non-Ultra +levels when the product supports subagents. + +Use Extra High when High is insufficient and the expected improvement justifies +additional latency and usage. It should not be the automatic default for +ordinary work. + +### Max + +"Quality matters more than speed" means the selected model receives still more +time to reason about one task. OpenAI describes Max as appropriate for the +hardest problems, particularly when additional exploration and verification +matter more than latency or usage. + +Max is defined by additional reasoning time for the selected model, not by an +exclusive ban on subagents. Use it for difficult integrated problems where +deep analysis is more important than a fast response. Explicit subagent use +can still be requested separately when supported. + +### Ultra + +"Demanding work using multiple agents" means more than increasing the primary +model's reasoning effort. Ultra uses maximum reasoning and permits Codex to +delegate suitable parts of the task to subagents, run those workstreams in +parallel, and synthesize their results proactively. + +Ultra does not promise that every request will be delegated. Delegation depends +on whether Codex identifies suitable work that benefits from decomposition. + +Use Ultra for large problems that divide into meaningful independent parts, +such as parallel repository reviews, multiple research lanes, or separable +implementation and verification work. Ultra is usually wasteful for small, +sequential, tightly coupled, or indivisible tasks. + +## Max versus Ultra + +| Question | Max | Ultra | +| --- | --- | --- | +| Mechanism | More time on one task | Maximum reasoning plus subagents | +| Best task | Difficult and integrated | Difficult and decomposable | +| Delegation | Explicitly requestable | Proactive when suitable | +| Tradeoff | More latency and usage | Highest usage; parallel work | +| Example | One diagnosis or proof | Independent investigations | + +Ultra should not be interpreted as simply "one notch smarter than Max." It +permits a different execution topology through proactive multi-agent work. + +## How to interpret the selector phrases + +- **"Fast responses":** the setting favors lower latency; it is not a + response-time guarantee. +- **"Lighter reasoning":** less internal deliberation relative to higher + settings; not zero reasoning. +- **"Balances speed and reasoning depth":** a general-purpose tradeoff rather + than a numerical midpoint. +- **"Greater reasoning depth":** more opportunity for planning, alternatives, + checks, and verification. +- **"Quality matters more than speed":** accept greater latency and usage when + difficult-task reliability is the priority. +- **"Using multiple agents":** Codex may decompose the task and delegate + parallel work to subagents. +- **"Consumes usage limits faster":** higher-effort and multi-agent runs can + consume more of the account's available usage. + +## Selection guidance + +1. Start with Medium for ordinary Codex work. +2. Choose Low when the task is narrow and latency matters. +3. Choose High for complex reasoning, debugging, planning, or review. +4. Choose Extra High when representative difficult tasks show a material gain + over High. +5. Choose Max for an exceptionally difficult integrated problem where depth is + worth the added time and usage. +6. Choose Ultra only when the task can be split into useful parallel + workstreams and synthesis will add value. + +OpenAI recommends using the lowest effort that reliably produces the needed +result. The appropriate setting should be evaluated on representative work +rather than inferred from the label alone. + +## Evidence and limitations + +### Directly supported by OpenAI documentation + +- Reasoning effort guides how much the model thinks. +- Lower effort favors speed and lower token usage. +- Higher effort permits more complete reasoning and can improve quality. +- Reasoning is adaptive rather than a fixed token allocation. +- Effort support and defaults depend on the selected model. +- Max gives the selected model more time to reason about one task. +- Non-Ultra levels can use explicitly requested subagents when supported. +- Ultra permits proactive subagent use for suitable decomposable work. + +### Interpretation rather than published guarantee + +- The levels form useful relative operating points, but OpenAI does not publish + a fixed multiplier between adjacent levels. +- No exact latency, token, quality, or correctness guarantee follows from a + label. +- The same label should not be assumed to provide identical behavior across + model families or future releases. +- Product wording, availability, entitlements, and usage accounting can change. + +## Sources + +All online sources below are first-party OpenAI documentation accessed on +July 13, 2026. + +1. OpenAI, "Models" (Codex) - model selection, effort guidance, Max, and Ultra. + +2. OpenAI, "Reasoning models: Reasoning effort" - definition, adaptive + reasoning, tradeoffs, and workload guidance for Low through `xhigh`. + +3. OpenAI, "Subagents: Choosing models and reasoning" - effort selection and + Ultra's proactive subagent delegation. + +4. OpenAI, "Model guidance: What is new" - GPT-5.6 Max reasoning and the + relationship between multi-agent operation and Codex Ultra. + +5. OpenAI, "Control verbosity from reasoning effort" - separate + `text.verbosity` and `reasoning.effort` controls. + +6. Operator-provided Codex CLI selector transcript, July 13, 2026 - exact local + selector wording recorded above. +7. Local verification on Anvil, July 13, 2026 - `codex --version` returned + `codex-cli 0.144.3`. + +## Refresh trigger + +Recheck this note against current first-party documentation when Codex changes +its model picker, reasoning labels, Max or Ultra behavior, account eligibility, +or usage-limit presentation. diff --git a/docs/provider-neutral-model-reasoning-self-research-playbook-2026-07-13.md b/docs/provider-neutral-model-reasoning-self-research-playbook-2026-07-13.md new file mode 100644 index 0000000..512a76f --- /dev/null +++ b/docs/provider-neutral-model-reasoning-self-research-playbook-2026-07-13.md @@ -0,0 +1,395 @@ +# Provider-Neutral Model and Reasoning Self-Research Playbook + +Status: candidate companion artifact. This playbook is provider-neutral, +exploratory, and non-canon. + +Date: July 13, 2026. + +Companion example: +[OpenAI Codex Reasoning Levels: Operational Definitions](openai-codex-reasoning-levels-2026-07-13.md) + +## Purpose + +This playbook teaches an AI agent to research and explain the model, +reasoning, intelligence, thinking, or effort controls exposed by its own +provider and product surface. + +It is designed for agents such as Claude, Gemini, Copilot, Devin, OpenCode, +local-model assistants, and future systems whose terminology may differ from +OpenAI Codex. + +The method produces an evidence-bounded research note that answers: + +- What exact choices does the product expose? +- What does the provider claim each choice changes? +- What tradeoffs does the provider associate with each choice? +- Are the choices a simple scale, different models, or different execution + architectures? +- What is directly documented, locally observed, inferred, or still unknown? + +## Core boundary + +An agent researching "itself" does not have privileged introspective access to +its hidden reasoning process, training implementation, or internal compute +allocation. + +The agent may inspect and report: + +- Its exposed model identifier and product version. +- Selector labels and descriptions visible in the user interface or CLI. +- Configuration fields, supported values, and documented defaults. +- First-party provider documentation. +- Observable behavior from bounded tests, when clearly labeled as an + experiment rather than a product guarantee. + +The agent must not treat its own generated explanation, hidden +chain-of-thought, or unaudited model memory as authoritative evidence about the +provider's implementation. + +## Required evidence classes + +Every material claim should be assigned one of these classes. + +### Observed + +Directly captured from the current product surface, such as a model picker, +CLI help screen, settings page, status command, or configuration schema. + +Record the product, surface, version, date, account context when relevant, and +the exact visible wording. Observation establishes what the interface says, +not whether the description is complete. + +### Documented + +Supported by current first-party provider documentation, API reference, +product manual, model card, release note, or official support article. + +Record the page title, direct URL, relevant section, access date, and the +smallest accurate paraphrase of the claim. + +### Experimentally observed + +Produced by a bounded, reproducible comparison run. Record the prompt, model, +settings, environment, number of trials, outputs or metrics, and limitations. + +A small experiment can show observed behavior in that test. It cannot prove a +universal implementation detail or service-level guarantee. + +### Inferred + +A conclusion derived from observations and documentation but not stated +directly by the provider. Explain the reasoning and keep the wording bounded. + +Use phrases such as "this suggests," "operationally," or "the most supported +interpretation is." + +### Unknown + +Not established by available first-party evidence or reproducible tests. +Preserve the unknown rather than filling it with plausible speculation. + +## Research workflow + +### 1. Establish identity and scope + +Record: + +- Provider and product name. +- Product surface, such as CLI, IDE, desktop app, web app, or API. +- Installed product version or observed build date. +- Active model identifier, if exposed. +- Current reasoning or thinking setting, if exposed. +- Research date and timezone. + +Do not assume that the product brand, model family, agent wrapper, and API +model identifier are the same thing. + +### 2. Capture the exact selector + +Open the model or reasoning selector without changing the active setting unless +the operator authorizes a change. Transcribe or capture: + +- Every visible model name. +- Every visible level or mode. +- Default and current markers. +- Concise descriptions, warnings, eligibility notes, and usage notices. +- Nested or advanced menus. + +If the agent cannot access its interactive selector, ask the operator to paste +the selector text or provide a screenshot. Treat operator-supplied text as an +observation with stated provenance. + +### 3. Inventory adjacent controls + +Determine whether the product exposes separate controls for: + +- Model choice. +- Reasoning, thinking, intelligence, or effort. +- Visible response verbosity. +- Context length or memory. +- Speed, service, or priority tier. +- Tool access and permissions. +- Search, browsing, or connector access. +- Agent count, delegation, or parallel execution. +- Planning mode or autonomy. + +Do not collapse these controls into one concept. A mode called "Advanced" or +"Deep" may alter orchestration rather than only increasing reasoning effort. + +### 4. Search first-party sources + +Search the provider's official documentation using the exact UI terms first. +Prefer this source order: + +1. Current product manual or official product documentation. +2. Official API reference or configuration reference. +3. Official model page or model card. +4. Official release notes or support documentation. +5. Provider-authored technical paper or system card. + +Use third-party sources only to identify questions or leads. Do not use them as +authority for what the provider means when a first-party source is available. + +If first-party sources disagree, record the conflict, page dates, product +surfaces, and likely scope difference. Do not silently choose the more +convenient wording. + +### 5. Map UI labels to documented controls + +For each visible label, determine: + +- Its configuration or API value, if documented. +- Whether it is supported by every model or only a subset. +- Whether the default is model-dependent, product-dependent, or universal. +- Whether it changes a scalar effort budget or selects a different mode. +- Whether it enables tools, agents, parallelism, or other architecture. +- Whether a product-facing mode maps to an ordinary API parameter value. +- The provider-stated latency, usage, cost, and quality tradeoffs. +- Recommended task types and any provider warnings. + +Do not infer a numerical mapping from ordinal names such as Low, High, Max, +Fast, Deep, or Pro unless the provider publishes that mapping. + +### 6. Define what each phrase means + +Translate marketing or selector language into bounded operational terms. + +For example: + +- "Fast" normally indicates a latency preference, not a response-time + guarantee. +- "Deeper" may indicate more deliberation, but not a documented multiplier. +- "Better quality" means an intended tradeoff, not guaranteed correctness. +- "More thinking" does not necessarily mean a longer visible response. +- "Multi-agent" indicates a different execution topology, not merely a larger + single-agent budget. + +Every translation must be traceable to documented language or labeled as an +inference. + +### 7. Identify non-scalar modes + +Test whether the choices form one ordered scale. Look specifically for modes +that introduce: + +- Subagents or parallel workers. +- Proactive, automatic, permitted, or explicitly requested delegation. +- External search or research pipelines. +- Tool-use policies. +- Multiple candidate generations or internal verification. +- Longer-running asynchronous execution. +- Different models, routing, or service tiers. + +Describe these separately from scalar reasoning levels. Do not place a +multi-agent mode at the top of a single-agent scale without qualification. A +mode that permits proactive delegation does not necessarily delegate every +request, and lower modes may still allow explicitly requested subagents. + +### 8. State what the control does not change + +Check and document whether the setting changes any of the following: + +- Base model. +- Knowledge or training cutoff. +- Context capacity. +- Visible verbosity. +- Permissions. +- Tools and connectors. +- Data-handling policy. +- Correctness guarantees. + +If the provider does not document the boundary, mark it Unknown. + +### 9. Write the research artifact + +Use the output contract below. Preserve exact selector wording separately from +interpretation, and place citations next to the claims they support. + +### 10. Verify and refresh + +Before closeout: + +- Reopen every cited first-party page. +- Confirm that each citation supports the adjacent claim. +- Check that observations include version and date context. +- Search for unsupported absolutes such as "always," "guarantees," "exactly," + or "twice as much." +- Run the repository's Markdown or document validation. +- Record a refresh trigger for product, model, or selector changes. + +## Reusable agent prompt + +The operator can give the following prompt to another provider's agent. + +```text +Research and document what your provider and current product surface mean by +every model, reasoning, intelligence, thinking, effort, or advanced mode shown +in your model selector. + +First, report your provider, product surface, installed or visible version, +active model, and current setting. Capture the exact selector labels, +descriptions, defaults, warnings, nested menus, and usage notices. Do not change +the active setting unless I authorize it. If you cannot inspect the selector, +ask me to paste its text or attach a screenshot. + +Then verify the terminology against current first-party provider documentation. +Prefer the product manual, API or configuration reference, official model page, +release notes, and system or model cards. Do not use your own model memory as +authority. Do not expose or claim access to hidden chain-of-thought. + +Separate every material claim into Observed, Documented, Experimentally +observed, Inferred, or Unknown. Distinguish model choice from reasoning effort, +response verbosity, context, permissions, tools, service tier, planning mode, +and multi-agent orchestration. Identify any mode that changes execution +architecture rather than merely increasing a scalar effort level. Distinguish +proactive delegation from explicitly requested delegation, and do not assume a +mode will delegate every request. + +For each option, define what the provider's description means operationally, +when to use it, its documented tradeoffs, and what it does not guarantee. Do +not invent fixed token, time, cost, quality, or capability multipliers. + +Produce a dated, provider-neutral research artifact using this structure: +Research question; short answer; observed selector; control map; definition by +level or mode; exceptional modes; phrase decoder; selection guidance; evidence +and limitations; first-party sources with access dates; refresh trigger. +``` + +## Output contract + +The resulting artifact should contain these sections. + +### Header + +- Title. +- Candidate or adopted status. +- Research date. +- Provider, product, surface, and version. + +### Research question + +State the exact terminology being investigated. + +### Short answer + +Explain the control in plain language and summarize the major tradeoff without +claiming undocumented precision. + +### Observed selector + +Record exact product wording, current and default markers, and observation +provenance. + +### Control map + +Separate model, reasoning, verbosity, context, permissions, tools, service +tier, planning, and orchestration controls. + +### Definition by level or mode + +For every option, include: + +- Exact label and provider description. +- Documented mechanism or intended effect. +- Appropriate task shapes. +- Latency, usage, cost, or quality tradeoffs. +- Explicit non-guarantees. +- Evidence class and source. + +### Exceptional modes + +Explain modes that change model routing, tool access, delegation, parallelism, +or execution architecture. + +### Evidence and limitations + +Separate documented facts, local observations, experiment results, inferences, +conflicts, and unknowns. + +### Sources + +Use direct first-party links with page titles, relevant sections, and access +dates. Include local version or selector evidence without exposing credentials +or private account data. + +### Refresh trigger + +Name the product changes that require the artifact to be revalidated. + +## Self-review questions + +Before presenting the result, the researching agent should answer: + +1. Did I verify my actual product surface and version? +2. Did I preserve the exact selector wording separately from interpretation? +3. Does every material provider claim have a first-party source? +4. Did I distinguish model selection from reasoning and orchestration? +5. Did I distinguish proactive delegation from explicitly requested agents? +6. Did I mistake a marketing adjective for a numerical specification? +7. Did I claim access to hidden reasoning or implementation details? +8. Did I label experiments and inferences rather than presenting them as + provider facts? +9. Did I preserve contradictions and unknowns? +10. Did I avoid exposing account data, credentials, or private configuration? +11. Did I record when this artifact must be refreshed? + +Any "no" answer is a blocker to an authoritative-sounding closeout. + +## Common failure modes + +- **Self-memory as authority:** the agent answers from training memory instead + of current first-party sources. +- **Surface collapse:** model, reasoning, verbosity, permissions, and agent + topology are described as one intelligence scale. +- **Ordinal overclaim:** High or Max is assigned an invented token or quality + multiplier. +- **Architecture blindness:** a multi-agent or research mode is treated as only + more single-agent thinking. +- **Orchestration exclusivity:** proactive delegation at one level is + misreported as proof that lower levels cannot use explicitly requested + agents. +- **Version blindness:** selector wording is recorded without product version + or observation date. +- **UI-as-specification:** concise interface copy is treated as a complete + technical contract. +- **Experiment overreach:** one prompt comparison is generalized to every task. +- **Source laundering:** unofficial commentary is cited as the provider's + definition. +- **Chain-of-thought claim:** the agent presents hidden reasoning as inspectable + evidence. +- **Stale permanence:** a time-sensitive product description is written as + timeless fact. + +## Minimum completion criteria + +The companion research is complete only when: + +- The selector or equivalent configuration surface is captured. +- The product and version context is recorded. +- Current first-party sources have been checked. +- Each label has a bounded operational definition. +- Scalar effort and architectural modes are separated. +- Claims are classified by evidence type. +- Unknowns and conflicts remain visible. +- The artifact contains sources, access dates, and a refresh trigger. +- Repository validation passes.