From 62c96b4885110c35391e5fddd141f898ff9fd86a Mon Sep 17 00:00:00 2001 From: Artur Mukhamadiev Date: Tue, 25 Aug 2026 19:00:09 +0300 Subject: [PATCH] init --- AGENTS.md | 247 +++++++++++++++++++++++++++ skills/linux-chromium-build/SKILL.md | 191 +++++++++++++++++++++ skills/lsp-cli/SKILL.md | 63 +++++++ skills/lsp-cli/lsp-cli.py | 1 + skills/webos-ose-build/SKILL.md | 117 +++++++++++++ 5 files changed, 619 insertions(+) create mode 100644 AGENTS.md create mode 100644 skills/linux-chromium-build/SKILL.md create mode 100644 skills/lsp-cli/SKILL.md create mode 120000 skills/lsp-cli/lsp-cli.py create mode 100644 skills/webos-ose-build/SKILL.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..411f810 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,247 @@ +# Mandatory Skill Routing + +Skills are mandatory procedures, not optional reference material. + +Before performing any specialized operation, identify the applicable skill(s) +and read their `SKILL.md` before executing the operation. + +Examples of specialized operations include: +- building; +- running tests; +- C/C++ semantic analysis; +- compiler-diagnostic analysis; +- debugging; +- code generation. + +If an applicable skill exists: +- MUST use that skill. +- MUST NOT construct an alternative procedure from memory. +- MUST NOT silently substitute another tool or workflow. +- MUST follow the skill's preconditions before executing its commands. + +If no applicable skill can be identified for an operation that requires one: +report this to the user and STOP before performing that operation. + +# General Workflow + +- **User Guidance:** Proactively communicate your plan and the reason for each + step. +- **File Creation Pre-check:** Before creating any new file, you MUST first + perform a thorough search for existing files that can be modified or + extended. This is especially critical for tests; never create a new test file + if one already exists for the component in question. Always add new tests to + the existing test file. +- **Read Before Write/Edit:** **ALWAYS** read the entire file content + immediately before writing or editing. +- **Problems on the way:** **ALWAYS** report to user if something is not working + as expected from Skills or AGENTS.md +- **Missing in environment:** **ALWAYS** report to user if something is missing + in work environment + +## Hard Stops + +An unexpected command failure is terminal for the current turn. This includes a +non-zero exit status, a missing required tool or configuration, an unavailable +service, malformed required output, or a denied permission, unless the user +explicitly asked to investigate that failure. + +On such a failure, immediately report the command or operation, its exit status +or failure condition, and the complete preserved failure output or its log +location. Then STOP. Do not retry, substitute a command, run further diagnosis, +kill a process, clean output, regenerate configuration, or edit code until the +user gives a new instruction. + +For C/C++ edits, a language-server diagnostic error is also a hard stop before +any build. Use the applicable diagnostic skill to run diagnostics for every +modified C/C++ source or header file. Report all errors and warnings; do not +build while any error remains or when diagnostics cannot be run. + +## Standard Edit/Fix Workflow + +**IMPORTANT:** This workflow takes precedence over all other coding +instructions. Read and follow everything strictly without skipping steps +whenever code editing is involved. Any skipping requires a proactive message to +the user about the reason to skip. + +1. **Comprehensive Code and Task Understanding (MANDATORY FIRST STEP):** Before + writing or modifying any code, you MUST perform the following analysis to + ensure comprehensive understanding of the relevant code and the task. This + is a non-negotiable prerequisite for all coding tasks. + - **a. Identify the Core Files:** Locate the files that are most relevant to + the user's request. All analysis starts from these files. + - **b. Conduct a Full Audit:** + - **IMPORTANT** For deeper understanding language server should be used if available. + - Read the full source of **EVERY** core file. + - For each core file, summarize the control flow and ownership semantics. + State the intended purpose of the core file. + - **c. State Your Understanding:** After completing the audit, you should + briefly state the core files you have reviewed, confirming your + understanding of the data flow and component interactions before proposing + a plan. + - **d. Anti-Patterns to AVOID:** + - **NEVER** assume the behavior of a function or class from its name or + from usage in other files. **ALWAYS** read the source implementation. + - **ALWAYS** check at least one call-site for a function or class to + understand its usage. The context is as important as the implementation. +2. **Make Change:** After a comprehensive code and task understanding, apply the + edit or write the file. + - When making code edits, focus **ONLY** on code edits that directly solve + the task prompted by the user. + - After modifying C/C++ source or header files, run the applicable + language-server diagnostics before proceeding to a build. Follow the + **Hard Stops** section if diagnostics find an error or cannot run. +3. **Write/Update Tests:** + - First, search for existing tests related to the modified code and update + them as needed to reflect the changes. + - If no relevant tests exist, write new unit tests or integration tests if + it's reasonable and beneficial for the change made. + - If tests are deemed not applicable for a specific change (e.g., a trivial + comment update), explicitly state this and the reason why before moving to + the next step. +4. **Build:** **ALWAYS** build relevant targets after making edits. +5. **Fix compile errors:** **ALWAYS** follow these steps to fix compile errors. + - **ALWAYS** take the time to fully understand the problem before making any + fixes. + - **ALWAYS** read at least one new file for each compile error. + - **ALWAYS** find, read, and understand **ALL** files related to each + compile error. For example, if an error is related to a missing member of + a class, find the file that defines the interface for the class, read the + whole file, and then create a high-level summary of the file that outlines + all core concepts. Come up with a plan to fix the error. + - **ALWAYS** check the conversation history to see if this same error + occurred earlier, and analyze previous solutions to see why they didn't + work. + - **NEVER** make speculative fixes. You should be confident before applying + any fix that it will work. If you are not confident, read more files. +6. **Test:** **ALWAYS** run relevant tests after a successful build. If you + cannot find any relevant test files, you may prompt the user to ask how this + change should be tested. +7. **Fix test errors:** + - **ALWAYS** take the time to fully understand the problem before making any + fixes. +8. **Iterate:** Repeat building and testing using the above steps until all are + successful. + +# Chromium Directives + +## Paths + +- All files in Chromium's source can be read by substituting `chromium/src` or + `//` for the current workspace (which can be determined by running + `gclient root` and appending `/src` to the output). + +## Building + +- Do not attempt a build without first establishing the correct output + directory and target. If you have not been given them, and you plan on doing + a build, then stop and ask before starting on any other tasks. +- Unless otherwise instructed, ask user for build environment details +- Immediately before launching a Chromium build, use the applicable build + skill's pre-launch procedure to verify the configured locations, environment + variables, wrapper, output directory, and target. +- Check for an existing Chromium build before launching a new one. If one is + running, report it and STOP. Never kill, restart, or replace a running build + without the user's explicit permission. +- When reporting build status from a log, cite only output produced after the + current build session was launched. Do not treat earlier log sessions as + evidence about the current build. + +## Testing + +Unless otherwise instructed, ask user on test running details + +When using `tools/autotest.py`: +- Do not invoke `autoninja` beforehand because `autotest.py` automatically + builds relevant targets. +- Build targets containing colons (`:`) are not valid inputs for + `{RELEVANT_TEST_FILENAMES}`. + +## Coding + +- Stay on task: Do not address code health issues or TODOs in code unless it is + required to achieve your given task. +- Add code comments sparingly: Focus on *why* something is done, not *what* is + done. + +# Knowledge Base (adapted from `agents/prompts/knowledge_base.md`) + +You MUST NOT answer from your general knowledge alone. The Chromium codebase is +vast and specific. Before answering any query, consult the relevant docs and +source. Canonical documentation is in `docs/`, and Chromium-specific docs exist +throughout `docs/`. + +Use this guide to decide which documents to consult: + +## Core Programming Patterns + +- **Communication between components/processes (e.g., browser-to-renderer):** + Look for **Mojo IPC interfaces (`.mojom` files)** that define the protocol + between components. Read the `.mojom` file to understand the data structures + and methods. +- **Asynchronous operations or threading:** Look for usage of + `base::TaskRunner` and `base::BindOnce`/`base::BindRepeating` for posting + tasks to the correct sequence or thread. +- **Code inside `third_party/blink/renderer/`:** + Blink has its own memory management and containers. **You MUST use container + and string types from `third_party/blink/renderer/platform/wtf/`** (e.g., + `blink::Vector`, `blink::String`) and **Oilpan for GC** (`Member<>`, + `WeakMember<>`, `Persistent<>`). **DO NOT** use STL containers or most `base/` + equivalents inside Blink code. +- **Threading/Callbacks:** + - Threading (`base::Thread`, `base::TaskRunner`, `base::PostTask`, sequences): + consult `docs/threading_and_tasks.md`. + - Callbacks (`base::OnceCallback`, `base::RepeatingCallback`, `base::Bind`): + consult `docs/callback.md`. + +## Adding a User Preference (Pref) +For prefs/settings (`pref`, `preference`, `setting`, `PrefService`): consult +`components/prefs/README.md`. + +## Adding a New UMA Metric + +- For UMA histograms/metrics: consult `docs/metrics/uma/README.md`. + +## Modifying BUILD.gn files + +- For style/best practices: consult `docs/imported/gn/style_guide.md`. + +## Adding a New UKM Metric + +- For UKM metrics: consult `tools/metrics/ukm/README.md`. + +## Debugging + +- **Header file not found:** + 1. Verify `deps` in the `BUILD.gn` of the failing target. + 2. Verify the `#include` path. + 3. (Infer from Target System Skill, if presented) Regenerate build files: `gn gen `. + 4. (Infer from Target System Skill, if presented) Confirm GN sees the dep: `gn desc //failing:target deps`. + 5. (Infer from Target System Skill, if presented) Check for issues: `gn check //failing:target`. +- **Linker error (undefined symbol):** check the target providing the symbol is + in `deps` (`gn desc`), and that `is_component_build` is set as expected in + `args.gn`. +- **Visibility error:** add the depending target to `visibility` in the + dependency's `BUILD.gn`. +- **General runtime debugging:** consult `docs/debugging.md`. + +# Landmines + +These rules exist because certain commands are too slow or crash/hang agents on +Chromium's large source tree, or because they are destructive. + +- Read files one at a time with the `read` tool. Do not batch-read or echo out + the entire contents of many large files in one turn. +- Any time you want to use `grep -r`, `grep -R`, or `git grep`, use `rg` + instead. +- Any time you want to use `find`, use `fdfind` instead. +- If running `rg` or `fdfind` fails because the executables are missing, tell + the user to install them with the following command, and then stop: + ``` + sudo apt-get install ripgrep fd-find + ``` +- Never directly install software with `brew` or `apt-get` - instead suggest + the required installation to the user with the full command line, and then + stop. +- Never amend git commits (`git commit --amend`). Always create new ones. +- Do not use recursive directory-wide searches that hang on this tree; prefer + targeted `rg`/`fdfind` queries. diff --git a/skills/linux-chromium-build/SKILL.md b/skills/linux-chromium-build/SKILL.md new file mode 100644 index 0000000..bfe5626 --- /dev/null +++ b/skills/linux-chromium-build/SKILL.md @@ -0,0 +1,191 @@ +--- +name: linux-chromium-build +description: >- + MANDATORY procedure for Linux x86 Chromium configure, build, test, and + build-failure investigation. Activate before proposing or executing a + build-neva wrapper, GN, Ninja, autoninja, Siso, or Chromium test command. + Verify configured locations, target/output directory, diagnostics, and active + build state; report and stop if a prerequisite fails. +--- + +# Linux Chromium Build + +Use this skill for Linux x86 Chromium builds and related tests. NEVA host builds +use `build-neva` wrappers. + +## Pre-launch hard stops + +Do not launch a build, configure, or test command until every applicable check +below has passed. If any check fails, report the missing or invalid value and +STOP. + +1. Check existing environment variables first. They may also be supplied in an + existing `.env` file: + - `CHROMIUM_SRC_DIR` — Chromium `src` checkout. + - `CHROMIUM_WRAPPER_DIR` — selected `build-neva` directory. + - `CHROMIUM_DEPOT_TOOLS_DIR` — parent `depot_tools` checkout. + - `CHROMIUM_BUILD_LOG` — log file for an unattended build. + + Use a set value exactly as supplied. In particular, if `CHROMIUM_BUILD_LOG` + is set, use it exclusively; do not construct another log path. An unattended + build requires `CHROMIUM_BUILD_LOG` to be set. Do not infer unverified + absolute locations from the current directory or relative candidates. + +2. Verify that `CHROMIUM_SRC_DIR`, `CHROMIUM_WRAPPER_DIR`, and + `CHROMIUM_DEPOT_TOOLS_DIR` exist and that the selected wrapper directory + contains the requested wrapper (`chrome.bash` or `unit_tests.bash`). + +3. Establish the exact output directory and target before a build. State the + target explicitly even when the wrapper selects its default browser target. + +4. If C/C++ source or header files changed, run the diagnostic procedure in + `lsp-cli/SKILL.md` for every modified file. Zero diagnostic errors is + required before a build. Report warnings. If diagnostics cannot run or + report any error, STOP. + +5. Check for active `autoninja`, Siso, or Ninja build processes. If any is + running, report it and STOP. Never kill, restart, or replace a running build + without explicit user permission. + +Start all builds from `$CHROMIUM_WRAPPER_DIR`. + +## Build Chromium + +Build the browser with the wrapper's required `depot_tools` ordering: + +```sh +cd "$CHROMIUM_WRAPPER_DIR" +PATH="$CHROMIUM_DEPOT_TOOLS_DIR:$CHROMIUM_WRAPPER_DIR/depot_tools:$PATH" \ +TERM=xterm \ +./chrome.bash +``` + +## Build a focused unit-test target + +For unattended runs, disable ccache as well: its setup can fail on `tput` under `set -e`. + +```sh +cd "$CHROMIUM_WRAPPER_DIR" +PATH="$CHROMIUM_DEPOT_TOOLS_DIR:$CHROMIUM_WRAPPER_DIR/depot_tools:$PATH" \ +CCACHE_DISABLE=1 \ +TERM=xterm \ +./unit_tests.bash +``` + +`unit_tests.bash` defaults to `out/unit_tests`. + +If you pass no target at all, get_all_targets_list() runs and builds every *_unittests +target in the tree (filtering out //third_party, //chrome, //tools, //testing, plus blink). + +The wrapper (unit_tests.bash) expects a GN label, and it strips the leading // before +passing to ninja (build_gn_target ${target#//}). So the format is: + +```sh +//extensions:extensions_unittests +//base:base_unittests +//content/test:content_unittests +``` + +And example call: + +```sh +# With // prefix (what the wrapper strips internally) +./unit_tests.bash "//content/test:content_unittests" + +# ninja-style, no prefix (also works since #// strips nothing) +./unit_tests.bash "content/test:content_unittests" +``` + +## Unattended builds and logs + +For a user-authorized new unattended build, start a new log session after the +pre-launch checks have passed. Truncate `CHROMIUM_BUILD_LOG` with `>` and write +a unique launch marker before starting the wrapper. Use `>>` only when +continuing that same already-running build session. + +When polling, read only output after the current launch marker (or its recorded +byte offset). Do not cite earlier log entries as evidence about the current +build. Expect `gclient sync`, GN generation, and Siso to take substantial time +before the compiler starts. + +```sh +cd "$CHROMIUM_WRAPPER_DIR" +build_session="codex-build-$(date -u +%Y%m%dT%H%M%SZ)" +: > "${CHROMIUM_BUILD_LOG:?set CHROMIUM_BUILD_LOG}" +printf '\n=== %s ===\n' "$build_session" >> "$CHROMIUM_BUILD_LOG" +nohup env \ + PATH="$CHROMIUM_DEPOT_TOOLS_DIR:$CHROMIUM_WRAPPER_DIR/depot_tools:$PATH" \ + CCACHE_DISABLE=1 \ + TERM=xterm \ + ./unit_tests.bash \ + >> "$CHROMIUM_BUILD_LOG" 2>&1 & +``` + +When Siso is enabled, dots and `S`/`F` markers indicate activity, not a +failure or successful completion. Confirm activity using the current session's +new output and the active Siso process. Treat only explicit terminal output +such as `Build Succeeded`, `Build Failure`, `FAILED:`, or compiler diagnostics +as a result. + +## Test Chromium + +Unless the user supplied the desired test command and environment, ask how +tests should run before executing them. Run the relevant test after a +successful build and use its output directory, for example: + +```sh +cd "$CHROMIUM_SRC_DIR/out/unit_tests" +./content_unittests --gtest_filter='.' +``` + +Another example with environment variables: + +```sh +cd "$CHROMIUM_SRC_DIR/out/unit_tests" +XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/1000}" \ +WAYLAND_DISPLAY="${WAYLAND_DISPLAY:-wayland-0}" \ +DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus \ +DISPLAY=:0 \ +./browser_tests --gtest_filter='.' \ + --no-sandbox \ + --headless=new \ + --enable-logging=stderr +``` + +## Debug Chromium failures + +Read the failing source, target `BUILD.gn`, and at least one call site before +changing code. Consult Chromium's relevant `docs/` and source rather than +relying on general knowledge. Use targeted `rg` queries; do not use recursive +`grep`, `git grep`, or `find` in this tree. + +- For a missing header, verify the target's `deps` and include path. Inspect + the existing, wrapper-configured graph with `gn desc` and `gn check` from + `$CHROMIUM_SRC_DIR`. Do not use direct `gn gen` as the normal regeneration + path: it bypasses the wrapper's `gclient` configuration, generated `args.gn`, + and ccache/icecc setup. Regenerate through `build-neva` instead: + + ```sh + cd "$CHROMIUM_WRAPPER_DIR" + PATH="$CHROMIUM_DEPOT_TOOLS_DIR:$CHROMIUM_WRAPPER_DIR/depot_tools:$PATH" \ + TERM=xterm \ + ./chrome.bash --configure + ``` + +### For a unit test + + ```sh + cd "$CHROMIUM_WRAPPER_DIR" + PATH="$CHROMIUM_DEPOT_TOOLS_DIR:$CHROMIUM_WRAPPER_DIR/depot_tools:$PATH" \ + CCACHE_DISABLE=1 \ + TERM=xterm \ + ./unit_tests.bash --configure + ``` +- For an undefined symbol, confirm the providing target appears in `deps` and + that `is_component_build` in `args.gn` matches the intended build. +- For a visibility error, inspect the dependency target's `visibility` before + changing it. +- For runtime problems, consult `docs/debugging.md` in the Chromium checkout. +- Changing USE_SISO from true to false will trigger full rebuild. +- If `gclient` is missing, verify that both the parent and wrapper + `depot_tools` directories are first on `PATH` in that order. diff --git a/skills/lsp-cli/SKILL.md b/skills/lsp-cli/SKILL.md new file mode 100644 index 0000000..b48af18 --- /dev/null +++ b/skills/lsp-cli/SKILL.md @@ -0,0 +1,63 @@ +--- +name: lsp-cli +description: >- + MANDATORY for Chromium C/C++ semantic analysis and compiler diagnostics. + Activate before exact symbol, definition, caller, implementation, + inheritance, or call-stack analysis, and after every C/C++ edit. Diagnostics + for every modified C/C++ file must report zero errors before a build; report + and stop when the CLI, session, or diagnostics are unavailable. +--- + +# lsp-cli (C++ MCP CLI) + +lsp-cli.py is a lightweight CLI front-end to the C++ MCP server. It connects +using the session cached in `.lsp-cli.json`. Use it for precise, index-backed +C++ symbol lookup in the large Chromium tree. + +## Hard stops + +Before semantic analysis or diagnostics, locate `lsp-cli.py` at the project +root or in this skill directory. If it is missing, report that exact condition +and STOP. + +The cached `.lsp-cli.json` session and its endpoint must be usable. If the +file is missing, its endpoint is unavailable, or a CLI command exits non-zero, +report the command and complete failure output, then STOP. Do not guess an +endpoint, try an alternate endpoint, or create or replace a session cache +without a new user instruction. + +## Required diagnostic gate + +After every C/C++ source or header edit, run diagnostics for every modified +file before starting a build: + +```sh +./lsp-cli.py show-diagnostics path/to/modified/file1.cc path/to/modified/file2.h +``` + +Report all errors and warnings. Zero errors is required to proceed to a build. +If diagnostics report any error, cannot cover every modified file, or fail to +run, report the result and STOP. Do not build, retry, or substitute another +compiler-diagnostic command until the user gives a new instruction. + +## How to get more information +```sh +./lsp-cli.py --help # to get available arguments and examples +./lsp-cli.py search-symbols --help #Help on how to search for C++ symbols in the codebase +./lsp-cli.py search-class --help #Help on how to search for C++ classes/structs/interfaces (kinds: Class, Struct, Interface) +./lsp-cli.py search-method --help #Help on how to search for C++ methods/functions/constructors (kinds: Method, Function, Constructor) +./lsp-cli.py analyze-symbol --help #Help on how to perform comprehensive analysis of a C++ symbol +./lsp-cli.py get-project-details --help #Help on how to get comprehensive project analysis including build configurations and global compilation database +./lsp-cli.py show-diagnostics --help #Help on how to show clangd diagnostics (errors/warnings/notes) for a source file +``` +`--build-directory` should be inherited from running server (no need to specify explicitly in normal usage) + +### Possible CLI locations + +- Project root +- skill directory + +## Why use lsp-cli.py + +The clangd index resolves qualified names and overloads reliably for the active +build configuration, yielding exact definitions and call sites. diff --git a/skills/lsp-cli/lsp-cli.py b/skills/lsp-cli/lsp-cli.py new file mode 120000 index 0000000..f7390df --- /dev/null +++ b/skills/lsp-cli/lsp-cli.py @@ -0,0 +1 @@ +/home/vptyp/git/mcp-cpp/tools/lsp-cli.py \ No newline at end of file diff --git a/skills/webos-ose-build/SKILL.md b/skills/webos-ose-build/SKILL.md new file mode 100644 index 0000000..383a00d --- /dev/null +++ b/skills/webos-ose-build/SKILL.md @@ -0,0 +1,117 @@ +--- +name: webos-ose-build +description: >- + MANDATORY for Chromium-related webOS OSE BitBake builds, tests, and failure + investigation for Raspberry Pi 4 or qemu targets. Activate before proposing + or executing a container connection, BitBake command, target-specific image + or package rebuild, or diagnosis of container, recipe, task, or deploy + artifact failures. Verify the container environment, target/output, and + active build state; report and stop if a prerequisite fails. +--- + +# webOS OSE Chromium Build + +Use this skill for Chromium-related webOS OSE BitBake builds. + +## Pre-launch hard stops + +Do not connect to a build environment or launch BitBake until every applicable +check below has passed. If any check fails, report the missing or invalid value +and STOP. + +1. Check existing environment variables first. They may also be supplied in an + existing `.env` file: + - `WEBOS_BUILD_HOST` — host that provides the webOS OSE container. + - `WEBOS_BUILD_DIR` — build directory visible inside the container. + - `WEBOS_CONTAINER_SSH_PORT` — container SSH port. + - `WEBOS_BITBAKE_TARGET` — confirmed Chromium-related recipe or image target. + - `WEBOS_BUILD_LOG` — log file for an unattended BitBake run. + + Use a set value exactly as supplied. Do not guess an absolute path, + container port, BitBake target, or replacement log path. An unattended run + requires `WEBOS_BUILD_LOG` to be set. + +2. Verify that the build host, container port, build directory, and BitBake + target are all known. Establish the expected artifact or output before + starting a build. + +3. If C/C++ source or header files changed, run the diagnostic procedure in + `lsp-cli/SKILL.md` for every modified file. Zero diagnostic errors is + required before a build. Report warnings. If diagnostics cannot run or + report any error, STOP. + +4. Check for an active BitBake build in the selected container. If one is + running, report it and STOP. Never kill, restart, or replace a running build + without explicit user permission. + +The webOS OSE container provides the required older Python and toolchain. Do +not run BitBake from a modern host shell. After the pre-launch checks, enter +the build host and container, then initialize the environment inside it: + +```sh +ssh "$WEBOS_BUILD_HOST" +ssh -p "$WEBOS_CONTAINER_SSH_PORT" localhost +cd "$WEBOS_BUILD_DIR" +. oe-init-build-env +``` + +## Build Chromium-related targets + +Run the confirmed target after initializing the environment: + +```sh +bitbake "$WEBOS_BITBAKE_TARGET" +bitbake -C compile "$WEBOS_BITBAKE_TARGET" #for incremental build, after some changes in source code +``` + +Use an iterative task only when the user has confirmed that source-only changes +make it valid; otherwise run the normal target build. Do not override the +build directory's configured machine per command. + +## Unattended builds and logs + +For a user-authorized new unattended build, start a new log session after the +pre-launch checks have passed. Truncate `WEBOS_BUILD_LOG` with `>` and write a +unique launch marker before starting BitBake. Use `>>` only when continuing +that same already-running build session. + +When monitoring, read only output after the current launch marker (or its +recorded byte offset). Do not cite earlier log entries as evidence about the +current build. + +```sh +build_session="codex-bitbake-$(date -u +%Y%m%dT%H%M%SZ)" +: > "${WEBOS_BUILD_LOG:?set WEBOS_BUILD_LOG}" +printf '\n=== %s ===\n' "$build_session" >> "$WEBOS_BUILD_LOG" +nohup bitbake "$WEBOS_BITBAKE_TARGET" \ + >> "$WEBOS_BUILD_LOG" 2>&1 & +``` + +## Test Chromium-related artifacts + +Unless the user has supplied the test command and target environment, ask how +the Chromium artifact should be tested and STOP. After a successful build, +verify the requested image or package artifact in the configured deploy +directory before attempting deployment or runtime testing. + +Use only the target-specific deployment and test procedure confirmed by the +user or Chromium/webOS OSE documentation. Do not assume a board address, +package name, application, or launch command. + +## Debug BitBake failures + +An unexpected build, configure, or test failure is terminal for the current +turn. Report the command, exit status, and complete preserved failure output or +its log location, then STOP. Do not retry, clean state, or change configuration +until the user gives a new instruction to investigate the failure. + +- For Python, compiler, or host-tool failures, confirm that the command runs + inside the webOS OSE container after `oe-init-build-env`. +- For a missing recipe or task, inspect the available layer configuration and + the target's recipe before changing configuration. +- For a source change missing from the build, verify the recipe's configured + source revision and the task inputs before selecting an iterative rebuild. +- For an artifact failure, inspect the target's deploy output and the relevant + task log before proposing a recovery. +- Do not use destructive clean or state-removal tasks unless the user has + authorized their scope.