exclude: remove user-contributed domain-skills from vendored harness (#27)

* exclude: remove user-contributed domain-skills from vendored harness

Domain-skills (`agent-workspace/domain-skills/` post-PR-#229 +
top-level `domain-skills/` from PR #247) are user-contributed
site recipes maintained on browser-use/browser-harness. We
exclude them from browsercode's vendored tree on quality,
maintenance, and prompt-injection grounds. Browsercode (cloud-
first, performance-focused) curates its own skills server-side.

Mechanism — three places that all reference UPSTREAM.md §3
"Excluded paths" as the source of truth:

1. `script/check-harness-diff.sh` gains an `IGNORED_PATHS_REGEX`
   filter applied before the noise/expected/unexpected split, so
   future syncs treat upstream domain-skills changes as if they
   don't exist.
2. `harness-sync.md` step 5 documents the skip rule as a top-row
   action in the file-category table; sync agents pre-filter
   excluded paths instead of deciding per-file.
3. The directories themselves are removed from the vendored tree
   (`git rm -r`).

Runtime safety: `helpers.goto_url()` already guards with
`if d.is_dir():`, so absence is a clean no-op (no exception, no
missing key, no broken tool). Smoke-tested:
`from browser_harness import run, helpers, daemon, admin, _ipc`
imports cleanly; `browser-harness --version` prints 0.1.0.

Doc trims (`SKILL.md`, `README.md`, `install.md`) are minimal
surgical edits — only direct `domain-skills/` references are
removed; surrounding prose is preserved so future sync diffs
stay localized to specific lines. UPSTREAM.md §3 records these
as "expect ongoing drift on sync" so future sync agents reconcile
them hunk-by-hunk.

Net: 82 files removed (76 agent-workspace skills + 4 shopify-admin
+ 2 README files), 7 files modified, 1 PR. Maintenance cost going
forward: zero on the excluded paths (filtered automatically); small
on the three trimmed docs.

Refs: AGENTS.md, UPSTREAM.md \u00a73.

* revert doc-file trims; keep verbatim, plan custom prompt later

Per discussion in originating thread: `README.md` and `install.md`
are not referenced by any browsercode prompt or TS code, so trimming
them changed nothing the agent reads. `SKILL.md` IS referenced by
`packages/opencode/src/tool/browser-execute.txt`, but that pointer
is ours — long-term plan is to replace it with a browsercode-owned
prompt file that we evolve independently of upstream, which makes
vendored `SKILL.md` inert too.

Net: trimming these files added per-sync drift forever for zero
agent-behavior benefit. Reverting to upstream verbatim eliminates
the drift and keeps future syncs mechanical.

UPSTREAM.md §3 'Modified files' table loses three rows (only
`.gitignore` remains). Replaced with a paragraph explaining why
domain-skills mentions are tolerated in these files: the agent
never reads them, or won't once we own the prompt.

Verified: smoke test clean, `check-harness-diff.sh` post-revert
shows only the expected `.gitignore` divergence + 3 real upstream
commits we haven't synced (daemon.py, run.py, test_run.py).

Roadmap entry for the custom prompt replacement work tracked
separately in maintainer memory.

---------

Co-authored-by: bcode <bcode@agents.local>

Author: Alezander9

AGENTS.md

@@ -143,8 +143,9 @@ src-layout reorg):
 - `src/browser_harness/*.py` (`daemon.py`, `admin.py`, `helpers.py`,
   `run.py`, `_ipc.py`) — protected. Pull verbatim. If behavior change is
   needed, upstream a PR to `browser-use/browser-harness`.
-- `interaction-skills/`, `agent-workspace/domain-skills/` — verbatim.
-  Never edit.
+- `interaction-skills/` — verbatim. Never edit.
+- `(agent-workspace/)?domain-skills/` — **excluded** from vendored tree.
+  Sync agents skip these paths; see UPSTREAM.md §3 "Excluded paths".
 
 Sync workflow lives in `harness-sync.md`.
 

UPSTREAM.md

@@ -91,21 +91,38 @@ Each upstream has its own append-only table. Add a row every time you pull.
 
 ---
 
-## 3. Harness divergences
+## 3. Harness divergences and excluded paths
 
-Per-file record of where `packages/bcode-browser/harness/` deliberately differs from upstream. Read this *before* a sync diff so intentional differences aren't mistaken for missing features.
+Per-file record of where `packages/bcode-browser/harness/` deliberately differs from upstream, plus the list of paths excluded from the vendored tree entirely. Read this *before* a sync diff so intentional differences aren't mistaken for missing features and excluded paths aren't accidentally re-imported.
 
 Path-allowlist policy (decisions.md §3.7, §4.5; updated for upstream PR #229 src-layout reorg):
 
 - `agent-workspace/agent_helpers.py` — editable; primary BrowserCode extension surface. Divergences expected.
 - `src/browser_harness/*.py` (`daemon.py`, `admin.py`, `helpers.py`, `run.py`, `_ipc.py`) — protected. Pulled verbatim from upstream. If behavior change is needed, upstream a PR to `browser-use/browser-harness`.
-- `interaction-skills/`, `agent-workspace/domain-skills/` — verbatim from upstream. We never edit these.
+- `interaction-skills/` — verbatim from upstream. We never edit these.
+- `(agent-workspace/)?domain-skills/` — **excluded.** See "Excluded paths" below.
 - Other files (`pyproject.toml`, `LICENSE`, `README.md`, etc.) — divergence allowed but discouraged.
 
+### Excluded paths
+
+Upstream paths the vendored tree treats as if they don't exist. Sync agents skip them; the diff checker filters them out. The runtime guard in `helpers.py` (`if d.is_dir():` in `goto_url`) means absence is a clean no-op.
+
+| Pattern | Reason |
+|---|---|
+| `(agent-workspace/)?domain-skills/**` | User-contributed site recipes. Quality, maintenance, and prompt-injection concerns. Browsercode (cloud-first, performance-focused) curates its own skills server-side; OSS users get the harness without bundled recipes. Both upstream paths covered: post-PR-#229 `agent-workspace/domain-skills/` and the legacy/PR-#247 top-level `domain-skills/`. The exclusion is enforced in three places that all reference this row: `script/check-harness-diff.sh` (`IGNORED_PATHS_REGEX`), `harness-sync.md` step 5 ("Excluded paths" row), and the absence of these directories from the vendored tree. |
+
+### Modified files
+
 | File | Section | Direction | Reason |
 |---|---|---|---|
 | `.gitignore` | venv entry | added `.venv/` | smoke-test workflow creates `.venv/` in the harness dir; we ignore it. Upstream uses CWD-level venv so doesn't need this. |
 
+The vendored harness's `SKILL.md`, `README.md`, and `install.md` reference `agent-workspace/domain-skills/`, but we keep them verbatim from upstream. Rationale:
+
+- `README.md` and `install.md` are not referenced by any browsercode prompt or TS code — the agent never reads them. Their content is dead weight in the extracted cache, not agent-visible.
+- `SKILL.md` is referenced by `packages/opencode/src/tool/browser-execute.txt` today, but the long-term plan (see ROADMAP) is to replace that pointer with a browsercode-owned prompt file, making vendored `SKILL.md` inert too.
+- Trimming these files would generate per-sync drift forever for zero agent-behavior benefit. Keeping them verbatim costs nothing and keeps future syncs mechanical.
+
 ---
 
 ## Drift checker

harness-sync.md

@@ -28,7 +28,7 @@ git pull origin main
 Two things to read before touching anything:
 
 - **`UPSTREAM.md`** — the latest `To SHA` row under `### browser-use/browser-harness`. That is the last commit we synced to. It is the only source of truth for "what version is vendored."
-- **`UPSTREAM.md` §3 Harness divergences** — the table of files where we deliberately differ from upstream, with reasons. Read this *before* the diff so you know which differences are intentional and not "missing features."
+- **`UPSTREAM.md` §3 Harness divergences and excluded paths** — the table of files where we deliberately differ from upstream, plus the list of paths excluded from the vendored tree entirely. Read both *before* the diff so you know which differences are intentional and not "missing features," and which paths to skip outright.
 
 If the divergences table is empty (initial vendor state), every difference between us and upstream is unintentional drift; flag any in the PR.
 
@@ -65,14 +65,16 @@ This is where the agent earns its keep. For each file changed in `<recorded-sha>
 
 | File category | Action |
 |---|---|
-| Files not in our divergences table (incl. `src/browser_harness/*.py`, `agent-workspace/domain-skills/`, `interaction-skills/`, `tests/`, `pyproject.toml`, `LICENSE`, etc.) | Take upstream verbatim — `cp temp/browser-harness/<path> packages/bcode-browser/harness/<path>`. |
+| **Excluded paths** (`(agent-workspace/)?domain-skills/...`) | **Skip entirely.** Never copy in, never resurrect. See UPSTREAM.md §3 "Excluded paths". `script/check-harness-diff.sh` filters these out automatically. |
+| Files not in our divergences table (incl. `src/browser_harness/*.py`, `interaction-skills/`, `tests/`, `pyproject.toml`, `LICENSE`, etc.) | Take upstream verbatim — `cp temp/browser-harness/<path> packages/bcode-browser/harness/<path>`. |
 | Files in our divergences table | Read each upstream hunk. For each, decide: **take** (apply upstream change to our file), **skip** (our divergence wins, ignore upstream change), or **adapt** (rewrite our divergence to coexist with the upstream change). Update the divergences row if its reason or scope shifts. |
-| New upstream files | Copy in. |
+| New upstream files | Copy in (unless under an excluded path). |
 | Files we have but upstream removed | Decide: keep ours (record in divergences) or delete. |
 
 Path-allowlist policy stays in force during sync resolution as well as normal development:
 - `agent-workspace/agent_helpers.py` — editable, agent's primary extension surface (post PR #229).
 - `src/browser_harness/*.py` (`daemon.py`, `admin.py`, `helpers.py`, `run.py`, `_ipc.py`) — protected. Always take upstream verbatim. If upstream regresses, file an issue at `browser-use/browser-harness` and pin to the prior SHA, do not patch locally.
+- `(agent-workspace/)?domain-skills/` — **excluded.** Treat as if not in the upstream tree. Quality + prompt-injection concerns; user-contributed site recipes do not ship with browsercode. The runtime guard in `helpers.py` (`if d.is_dir():`) means this is a clean no-op.
 
 ### 6. Smoke test