From 5bade069f63d6c3c99e886ae0d7672a6f6cb5ba0 Mon Sep 17 00:00:00 2001
From: choiyounggi <74581798+choiyounggi@users.noreply.github.com>
Date: Fri, 14 Aug 2026 18:08:49 +0900
Subject: [PATCH] knowledge: ingest 3 verified insight(s)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- NEW backend/python/packaging/data-files-and-install-paths (NEW category
  packaging): __file__-relative data files break after pip install .;
  declare package data, resolve via importlib.resources, verify against a
  wheel in a scratch venv (setuptools + CPython docs; linkly rc=4 repro)
- testing/data/test-data-and-isolation: +orchestrator-injected env rows —
  unset LO_*-style coordination vars in setup, pass tempdir state paths
  explicitly; leaked values corrupt the live run's shared state (issue #100)
- qa/document-verification/editing-a-gated-document: +reflow breakage mode
  on the Substring anchor row, +platform-invisible-failure edge (bash <=4.0
  mid-test [[ ]] gap), measured 2026-08-14; harvested mechanism claim
  falsified and corrected (runtime half deferred to open PR #47)
---
 .dev-loop/INGEST_REPORT.md                    | 80 +++++++++----------
 INDEX.md                                      |  2 +-
 log.md                                        |  1 +
 wiki/backend/index.md                         |  2 +-
 wiki/backend/python/index.md                  |  6 ++
 .../packaging/data-files-and-install-paths.md | 65 +++++++++++++++
 .../agent-orchestration/shared-run-state.md   |  2 +-
 .../editing-a-gated-document.md               | 10 ++-
 wiki/qa/index.md                              |  2 +-
 wiki/testing/data/test-data-and-isolation.md  |  7 +-
 wiki/testing/index.md                         |  2 +-
 11 files changed, 125 insertions(+), 54 deletions(-)
 create mode 100644 wiki/backend/python/packaging/data-files-and-install-paths.md

diff --git a/.dev-loop/INGEST_REPORT.md b/.dev-loop/INGEST_REPORT.md
index 55ccfd1..ac1a101 100644
--- a/.dev-loop/INGEST_REPORT.md
+++ b/.dev-loop/INGEST_REPORT.md
@@ -1,53 +1,45 @@
-# Knowledge consolidation — 15 open PRs (#17–#40) → one reconciled state
-
-The 15 open `knowledge/*` PRs (created 2026-08-04 → 2026-08-05, before the
-harvest processed-store dedupe fix in #41) contained 123 file-versions of ~75
-unique pages, with the same insight landing at up to 3 different paths across
-up to 8 PRs. Per-PR review would re-import those duplicates, so — as with the
-#6–#13 consolidation — this branch carries the reconciled end-state and the 15
-PRs are closed in its favor.
+# Knowledge flush — 3 insight(s)
 
 ## Verified best-practice
 
-Every adopted page's sources were carried from its originating PR's flush, where
-they were live-verified at flush time; no new URLs were introduced during
-consolidation (checked mechanically: every `http(s)` URL in every merged page
-appears in a source PR's diff; every added body line in amended pages traces to
-a source PR hunk — orphan-line verification). Confidence fields were kept as the
-originating flushes set them, except client-side-rate-limiting where the union
-of provider-doc citations (Okta, Auth0, GitHub, OpenAI, RFC 6585) supports
-`verified` for the load-bearing claims. One subagent's fabricated content (12
-files matching neither main nor any PR, with invented source URLs) was detected
-by the same verification and replaced with true PR content.
+**1. `__file__`-relative data files break after non-editable install → package data + `importlib.resources`** (hash `a9e3db01b9b1ceb1`, linkly session)
+- Claim: a Python package locating runtime data files via `__file__`-relative paths works in editable/`PYTHONPATH` runs but fails after `pip install .`; data files must be declared as package data and resolved via `importlib.resources`.
+- Sources checked (fetched this flush): https://setuptools.pypa.io/en/latest/userguide/datafiles.html — "It is strongly recommended that, if you are using data files, you should use `importlib.resources` to access them"; `__file__` manipulation "isn't compatible with PEP 302-based import hooks, including importing from zip files"; `include_package_data`/`package_data` control wheel contents. https://docs.python.org/3/library/importlib.resources.html — resources "do not have to exist as physical files and directories"; `as_file()` yields a real path and cleans up extractions.
+- Field evidence: linkly v0.4.0 `lnpl build` rc=4, grammar path resolved to `.venv/lib/python3.13/mlir/lnpl.irdl.mlir` (absent from the wheel) while `PYTHONPATH=impl` built fine.
+- **Confidence: verified** (official docs + field reproduction).
+
+**2. Orchestrator-injected coordination env leaks into harness test suites** (hash `03b0983bb4a5d9d8`, dev-loop session)
+- Claim: when an orchestration worker runs the harness's own test suite, injected `LO_*`/`GROUNDWORK_*` vars leak into the scripts under test — tests fail against the unset-env baseline AND test writes land in the live run's shared state (watcher then monitors the wrong session). Unset injected vars in setup; pass tempdir state paths explicitly.
+- Sources checked: dev-loop issue #100 (OPEN, root cause section marked "verified 2026-08-14") — 6 deterministic `launch-session.bats` failures reproduced with `env LO_RUN_ID=… bats` on a clean checkout; live `t90.json` found rewritten with bats tempdir paths and a foreign session name. The env-merge mechanism (`env` merges into the inherited environment unless `-i`) is already sourced on the target page (pubs.opengroup.org env spec).
+- **Confidence: field-tested** (reproducible in-repo evidence; no additional external doc needed beyond what the page already cites).
+
+**3. Reflowing prose that tests assert as a single-line substring** (hash `4b8d97490dc0ed5e`, dev-loop session)
+- Claim as harvested: "macOS bash 3.2 matches a newline-split phrase in `[[ ]]`, so only ubuntu CI fails."
+- **Mechanism correction — the harvested claim is false.** Measured this flush on bash 3.2.57: `[[ "$s" == *"return to step 1"* ]]` does NOT match a newline-split phrase (NOMATCH on both old and new bash). What actually differs by platform: `set -e; [[ 1 -eq 2 ]]; echo REACHED` prints REACHED on bash 3.2 — under bash ≤4.0 a failing mid-test `[[ ]]` doesn't abort, so the broken assertion passes silently on macOS while bash ≥4.2 CI fails it. `tests/orchestrate-review-pass.bats:81` uses exactly this mid-test `[[ ]]` form.
+- Field evidence: two reproductions (dev-loop PR #94 §O3; PR #102 'return to step 1 of the dispatch', fixed by reflow commit 9cbc065).
+- **Confidence: verified** (directive verified with the corrected mechanism; the wrong mechanism was NOT ingested).
 
 ## Existing-layer check
 
-- Merged-main near-dup scan before consolidation: pairwise Jaccard over
-  title + "When this applies" across all 141 merged pages → **0 flagged pairs**;
-  previously merged content carries no duplication.
-- Cross-PR dedup during consolidation: 10 duplicate clusters collapsed to one
-  canonical page each (rate limiting 8→1, call-site enumeration 7→folded into
-  the canonical merged in #20, stderr/exit-0 diagnostics 4→1, sysroot 2→1,
-  env-off-switch 2→1, completion predicates 2→1, robots.txt 2→1,
-  harness-mediated results 2→1, leaked artifacts 2→1, orchestration category
-  naming unified). Three near-pairs kept distinct after trigger comparison,
-  with mutual `related:` links (differential setup vs interpretation; expansion
-  semantics vs off-switch design; import-time tactics vs level choice).
-- 24 existing pages received union-merged amendments; additions already present
-  in main (from #16/#20) were skipped, and all non-canonical `related:` ids
-  were remapped to canonical page ids (post-merge broken-link scan: 0).
+Pages read: qa-document-verification-editing-a-gated-document, testing-data-test-data-and-isolation, infrastructure-agent-orchestration-shared-run-state, infrastructure-agent-orchestration-worktree-isolated-workers
+
+- Grepped main's `wiki/` for `__file__`/`importlib`: zero hits → insight 1 is not covered anywhere; **created new page** (a stale local-only branch `knowledge/dch0202-20260805-144711` once drafted a related page but has no PR and is not in main — not an open-PR obligation).
+- `testing-data-test-data-and-isolation` already carries the generic absent-variable `unset` row and the env-derived-write-path row; insight 2's *injected-orchestration-env → live-state corruption* angle was missing → **merged** (+1 Do row, +1 edge case, +1 field-incident source), related-links added both ways with `infrastructure-agent-orchestration-shared-run-state`. No conflict with existing directives.
+- `qa-document-verification-editing-a-gated-document` covers anchor inventory before editing; its Substring anchor row lacked the reflow/line-wrap breakage mode and the platform-invisible-failure twist → **merged** (extended Substring row, +1 edge case, +1 Instead-of row, +2 sources), cross-linking existing `testing-quality-tests-that-cannot-fail`. No conflict.
+- `node scripts/wiki-lint-prohibitions.js`: 61 directives, 0 violations after edits.
+
+## Open-PR check
+
+Listed 27 open `knowledge/*` heads (gh pr list, head:knowledge/) and grepped `git diff origin/main...<head> -- wiki/` across all fetched knowledge branches for `importlib|__file__|package data|LO_|GROUNDWORK_|ambient env|unset|bats|bash 3.2|normalize_ws|line-wrap|whitespace`.
+
+- Insight 1: no open head touches Python packaging/`__file__` → **new**.
+- Insight 2: no open head touches injected-env test isolation (the generic absent-var row in old branch `dch0202-20260805-103148` / closed PR #28 is already in main) → **new**.
+- Insight 3: **partial fold into PR #47** (`knowledge/dch0202-20260806-130040`) — #47 already carries the runtime mechanism (bats mid-test `[[ ]]` trap under bash ≤4.0, tests-that-cannot-fail row, COMPAT + bats-gotchas sources). That part is NOT re-ingested here; a comment noting the two additional field reproductions (PR #94/#102) is left on #47. The document-editing side (reflow breaks single-line substring anchors; whitespace-normalize new phrase gates) is absent from #47 and from main → merged into `editing-a-gated-document` here as **new**.
 
 ## Routing decision
 
-- New categories: `infrastructure/agent-orchestration` (5 pages; unified the
-  competing `orchestration`/`agent-orchestration` names), `databases/data-survey`
-  (1), `qa/deliverables` (1). All other pages route into existing categories.
-- Canonical-path decisions: rate limiting → `backend/common/reliability/`
-  (sits beside timeouts-and-retries; 6 of 8 variants chose it); stderr
-  diagnostics → `platforms/processes/` (concern spans beyond shells); leaked
-  artifacts → `testing/data/artifact-leakage-from-a-suite`; call-site
-  enumeration → the existing `backend/common/change-impact/` page.
-- All 38 new pages listed in their domain indexes (nearest-index rule; backend
-  routes via its python sub-index for bytecode-cache-staleness); INDEX.md domain
-  summaries updated for infrastructure/qa/databases. Full-wiki lint: frontmatter,
-  ids, related-links, index coverage, size, qualifiers, staleness → 0 findings.
+| Insight | Target | Decision |
+|---------|--------|----------|
+| 1 — data files & install paths | `backend/python/packaging/data-files-and-install-paths.md` | **New page, NEW category `packaging`** — existing backend/python categories (concurrency, boundaries, serving, language) cover runtime behavior, not distribution/wheel contents; harvested "platforms" hint rejected (platforms = OS-level differences, this is install-mode-level). backend/python index + backend index + root INDEX updated |
+| 2 — injected coordination env | `testing/data/test-data-and-isolation.md` | **Merge** — trigger is "how a suite isolates state", same page that owns the absent-var and env-write-path rows; orchestration cross-link to shared-run-state rather than a new agent-orchestration page (the actor is the test author, not the brief author) |
+| 3 — reflow vs substring anchors | `qa/document-verification/editing-a-gated-document.md` | **Merge** — exact trigger match ("editing a document automated text gates check"); gate-authoring half folded as guidance pointing at whitespace-normalized comparison; runtime-mechanism half deferred to open PR #47 (fold) |
diff --git a/INDEX.md b/INDEX.md
index 3803c73..3b8cc0f 100644
--- a/INDEX.md
+++ b/INDEX.md
@@ -12,7 +12,7 @@ follow the cross-pointers in their index or take the next matching seeded domain
 | Domain | Status | Route here when |
 |--------|--------|-----------------|
 | [databases](wiki/databases/index.md) | **seeded** | Designing schemas/tables/keys, choosing or evaluating indexes, writing or optimizing queries, choosing transaction/isolation behavior, surveying live data to derive a rule, verifying additive migrations |
-| [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, call-site enumeration before a contract change, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors, consuming LLM APIs (completion validation, context budgeting), consuming external-API responses, externally-owned defaults, object-storage references) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps) |
+| [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, call-site enumeration before a contract change, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors, consuming LLM APIs (completion validation, context budgeting), consuming external-API responses, externally-owned defaults, object-storage references) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps, packaging data files with `importlib.resources`) |
 | [frontend](wiki/frontend/index.md) | **seeded** | Web UI code: state placement, rendering performance, in-UI data fetching (races, infinite scroll), auth token handling, forms, XSS-safe output, accessibility |
 | [infrastructure](wiki/infrastructure/index.md) | **seeded** | CI/CD pipelines, secrets in build/deploy, container image builds, rollout/rollback strategy, observability (logs/metrics/alerting), per-environment/path-valued config, multi-agent orchestration (worker liveness signals, shared run state, tmux pane delivery, completion gates, worktree-isolated workers) |
 | [testing](wiki/testing/index.md) | **seeded** | Writing or structuring automated tests: level choice, cases/assertions, test data, mock decisions, flaky tests (release-process quality → qa) |
diff --git a/log.md b/log.md
index bd066cf..5fb1a43 100644
--- a/log.md
+++ b/log.md
@@ -44,3 +44,4 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest|revise|lint|gap|contradiction|drif
 ## [2026-08-06] dedup | Cross-PR duplicate clusters collapsed: client-side rate limiting (8 PR versions at 3 paths → 1), call-site enumeration (7 versions at 7 paths → additions folded into the already-merged canonical page), stderr/exit-0 diagnostics (4 versions at 4 paths → 1), macOS sysroot (2→1), env-var off switch (2→1), completion predicates (2→1), robots.txt (2→1), harness-mediated results (2→1), leaked test artifacts (2→1), orchestration category naming (orchestration vs agent-orchestration → agent-orchestration). Kept distinct after trigger comparison: differential-testing vs differential-run-agreement (setup vs interpretation), unset-versus-empty-parameters vs env-var-off-switches (semantics vs design, cross-linked), import-time-side-effects vs test-level-choice edge (tactics vs level choice, cross-linked). Merged-main near-dup scan (Jaccard over title+trigger, 141 pages): 0 pairs — no duplication among previously merged content.
 ## [2026-08-06] ingest | Reconciled post-consolidation flush PRs #42–#43 (created against pre-#44 main). Folded unique content: platforms/filesystems/permissions-and-exec-bits (+`sh "$SCRIPT"` interpreter-invocation rows — stubs need no exec bit, avoids EDR chmod+x heuristics), platforms/shells/command-text-inspected-before-execution (+gate-AUTHOR step 8: parse all three POSIX quoting forms, expand only ~/$HOME/${HOME}; red-then-green bats evidence), testing/quality/checks-that-cannot-pass (+vacuously-green pre-implementation test row), platforms/processes/tool-diagnostics-without-a-failing-exit-code (+repeat-suppression edge, +clang reproduction source), infrastructure/ci-cd/secrets-handling (+independent credential channels row: gh token vs git SSH vs API token, git push --dry-run / author:@me probes), testing/mocking/what-to-mock (+ESM read-only-bindings DI rows, +PATH-emptied tripwire negative-proof). Dropped as duplicates of the #44 state: #42's rate-limit row (already in timeouts-and-retries + client-side-rate-limiting), #42's warning-only-diagnostics page (same trigger as tool-diagnostics-without-a-failing-exit-code), #42's leak-attribution row (already in test-data-and-isolation).
 ## [2026-08-12] revise | routing: disjoint scopes for the doc-gate cluster (testing/quality ↔ qa/document-verification) and the flaky pair (testing/flaky ↔ debugging/concurrency); INDEX backend LLM phrasing; databases→backup cross-pointer (#37)
+## [2026-08-14] ingest | knowledge-flush of 3 queued insights. New: backend/python/packaging/data-files-and-install-paths (NEW category packaging — `__file__`-relative data files break after non-editable install; declare package data + resolve via importlib.resources files()/as_file(); verify against a wheel installed into a scratch venv; setuptools + CPython docs verified, linkly v0.4.0 rc=4 reproduction). Merged: testing/data/test-data-and-isolation +1 Do row / +1 edge case (orchestrator-injected coordination env — unset in setup, pass tempdir state paths explicitly; leaked values also corrupt the live run's shared state; dev-loop #100 reproduction) with related↔shared-run-state; qa/document-verification/editing-a-gated-document +reflow breakage mode on the Substring anchor row, +platform-invisible-failure edge (bash ≤4.0 mid-test `[[ ]]` gap), +Instead-of row, measured 2026-08-14 + dev-loop PR #94/#102 field reproductions. Mechanism correction during verification: the harvested claim "macOS bash 3.2 matches a newline-split phrase in [[ ]]" was falsified by measurement — the wrap breaks the match on every platform; macOS only hides the failure (errexit compound-command gap, cross-linked to tests-that-cannot-fail / open PR #47).
diff --git a/wiki/backend/index.md b/wiki/backend/index.md
index 5689f57..d9dafec 100644
--- a/wiki/backend/index.md
+++ b/wiki/backend/index.md
@@ -8,7 +8,7 @@ three stack subtrees — route by concern first, stack second:
 | [common](#common-language-agnostic) (below) | The concern is language-agnostic: API contracts, enumerating call sites before a contract change, idempotency, JWT issuance, outbound calls, caching, jobs, transactions in app code, shared state/pools, exception structure, consuming LLM APIs (completion validation, context budgeting), consuming external-API responses, externally-owned defaults, object-storage references |
 | [java](java/index.md) | You are writing/reviewing JVM backend code (Java/Kotlin, Spring, JPA/Hibernate) and the concern is stack-specific: entity mapping, persistence context, proxy pitfalls, JVM threads/memory |
 | [node](node/index.md) | You are writing/reviewing Node.js/TypeScript backend code: event-loop blocking, promise error handling, runtime validation at boundaries, graceful shutdown |
-| [python](python/index.md) | You are writing/reviewing Python backend code: GIL/concurrency model, pydantic validation, WSGI/ASGI workers, language traps |
+| [python](python/index.md) | You are writing/reviewing Python backend code: GIL/concurrency model, pydantic validation, WSGI/ASGI workers, language traps, packaging data files and resolving them after install |
 
 Load a stack page IN ADDITION to the matching common page when both apply — common
 owns the principle, the stack page owns the mechanics. SQL, index, and DB-side
diff --git a/wiki/backend/python/index.md b/wiki/backend/python/index.md
index c0473f2..0c93ac7 100644
--- a/wiki/backend/python/index.md
+++ b/wiki/backend/python/index.md
@@ -24,6 +24,12 @@ Match your situation to a "load when" line; load only matching pages.
 |------|-----------|
 | [app-servers-and-workers](serving/app-servers-and-workers.md) | Deploying a Python web app behind gunicorn/uvicorn; choosing worker count, worker class (sync/gthread/ASGI), or worker timeout; requests queue or time out while CPU sits idle; workers killed mid-request; worker memory growth and preload/max_requests recycling decisions |
 
+## packaging
+
+| Page | Load when |
+|------|-----------|
+| [data-files-and-install-paths](packaging/data-files-and-install-paths.md) | A Python package reads non-code files (grammars, templates, KBs) located via `__file__`-relative paths; an installed console script cannot find a data file that exists in the repo; deciding how data files get into the wheel and how code resolves them after `pip install .` |
+
 ## language
 
 | Page | Load when |
diff --git a/wiki/backend/python/packaging/data-files-and-install-paths.md b/wiki/backend/python/packaging/data-files-and-install-paths.md
new file mode 100644
index 0000000..13ddfa7
--- /dev/null
+++ b/wiki/backend/python/packaging/data-files-and-install-paths.md
@@ -0,0 +1,65 @@
+---
+id: backend-python-packaging-data-files-and-install-paths
+domain: backend
+category: packaging
+applies_to: [python]
+confidence: verified
+sources:
+  - https://setuptools.pypa.io/en/latest/userguide/datafiles.html
+  - https://docs.python.org/3/library/importlib.resources.html
+last_verified: 2026-08-14
+related: [testing-data-test-data-and-isolation]
+---
+
+# A Python Package That Reads Data Files Shipped Next to Its Code
+
+## When this applies
+
+A Python package reads non-code files at runtime — grammar definitions, dialect
+files, templates, knowledge bases — and locates them with `__file__`-relative
+paths (`Path(__file__).parent / ...` or `.parents[N]`); or an installed console
+script cannot find a data file that exists in the repository.
+
+## Do this
+
+1. **Declare the data files as package data** so the build backend puts them in
+   the wheel: `include_package_data = True` (files matched by `MANIFEST.in` or
+   tracked by VCS) or explicit `package_data` / `tool.setuptools.package-data`
+   globs. A file the wheel does not contain cannot be found by any path logic
+   after install.
+2. **Resolve them by package name, not filesystem position**:
+   `importlib.resources.files("mypkg.data").joinpath("grammar.mlir").read_text()`.
+   When a real on-disk path is required (a subprocess takes a filename), wrap it
+   in `as_file()` — the context manager extracts from a zip when necessary and
+   removes the extraction on exit.
+3. **Keep every path anchor inside the package.** A `.parents[N]` walk that
+   escapes the package directory resolves into the venv's internals after a
+   non-editable install — the repo layout above the package does not exist in
+   `site-packages`.
+4. **Verify against a real non-editable install, not the checkout**: build and
+   install into a scratch venv with `pip install .` (no `-e`), then run the
+   entry point from a directory outside the repo. Editable installs and
+   `PYTHONPATH` runs anchor `__file__` in the repo, so they pass even when the
+   wheel ships zero data files.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| The data file must be handed to an external tool as a path | `with as_file(files("pkg.data") / name) as p:` and consume `p` inside the block — a zip extraction is deleted when the block exits |
+| Data lives outside any package directory (repo-root `data/`) | Move it under an importable package — setuptools includes data files per package, and `files()` resolves by importable name |
+| Python < 3.9 must run the code | Use the `importlib-resources` backport, which provides the same `files()` API |
+| Every existing test runs from the repo checkout | Add one job that installs the built wheel into a clean venv and smoke-tests the CLI from outside the repo — repo-anchored resolution failures are invisible to in-repo tests |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Compute a data path as `Path(__file__).resolve().parents[N] / "data"` | Resolve via `importlib.resources.files()` on the owning package | `__file__` anchors wherever the module was imported from; after `pip install .` that is `site-packages`, and the `parents[N]` walk lands inside the venv where the repo's directories do not exist |
+| Prove packaging works by running the suite in the checkout | Install the wheel into a scratch venv and run the entry point from outside the repo | Editable and `PYTHONPATH` runs resolve `__file__` to the repo, masking a wheel that ships no data files |
+
+## Sources
+
+- https://setuptools.pypa.io/en/latest/userguide/datafiles.html — "It is strongly recommended that, if you are using data files, you should use `importlib.resources` to access them"; `include_package_data` / `package_data` control what the wheel contains; `__file__` manipulation "isn't compatible with PEP 302-based import hooks, including importing from zip files"
+- https://docs.python.org/3/library/importlib.resources.html — packages and resources "do not have to exist as physical files and directories on the file system"; `as_file()` yields a `pathlib.Path` and cleans up any temporary extraction on exit
+- Field reproduction 2026-08-14 (linkly v0.4.0): installed `lnpl build` failed rc=4 — the `__file__`-anchored grammar path resolved to `.venv/lib/python3.13/mlir/lnpl.irdl.mlir`, which the wheel never shipped (`impl/lnpl/backend.py:63-64`), while `PYTHONPATH=impl` runs of the same source built fine
diff --git a/wiki/infrastructure/agent-orchestration/shared-run-state.md b/wiki/infrastructure/agent-orchestration/shared-run-state.md
index e026b0d..0fbd56a 100644
--- a/wiki/infrastructure/agent-orchestration/shared-run-state.md
+++ b/wiki/infrastructure/agent-orchestration/shared-run-state.md
@@ -8,7 +8,7 @@ sources:
   - https://git-scm.com/docs/git-worktree
   - https://man.openbsd.org/tmux
 last_verified: 2026-08-05
-related: [infrastructure-agent-orchestration-control-signals-vs-primary-artifacts, infrastructure-agent-orchestration-session-completion-gates, infrastructure-agent-orchestration-worktree-isolated-workers, backend-common-concurrency-distributed-locks, backend-common-jobs-scheduled-job-overlap]
+related: [infrastructure-agent-orchestration-control-signals-vs-primary-artifacts, infrastructure-agent-orchestration-session-completion-gates, infrastructure-agent-orchestration-worktree-isolated-workers, backend-common-concurrency-distributed-locks, backend-common-jobs-scheduled-job-overlap, testing-data-test-data-and-isolation]
 ---
 
 # Orchestration State Kept in a Shared Directory Inside the Repository
diff --git a/wiki/qa/document-verification/editing-a-gated-document.md b/wiki/qa/document-verification/editing-a-gated-document.md
index a3e0387..9a9552a 100644
--- a/wiki/qa/document-verification/editing-a-gated-document.md
+++ b/wiki/qa/document-verification/editing-a-gated-document.md
@@ -9,7 +9,7 @@ sources:
   - https://docs.vale.sh/topics/scopes.md
   - https://docs.vale.sh/checks/existence
   - https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md
-last_verified: 2026-07-30
+last_verified: 2026-08-14
 related: [qa-process-acceptance-criteria, qa-process-regression-scope, testing-quality-tests-that-cannot-fail]
 ---
 
@@ -32,7 +32,7 @@ now fails on wording whose meaning did not change.
 |-------------|---------|-----------------------|
 | Phrase or vocabulary | a pattern requiring/forbidding certain verbs near a term | Reworded sentence stops matching, or starts matching a forbidden pattern |
 | Line or row count | "file has 444 lines", "table has 5 rows" | Any insertion shifts the count |
-| Substring | a section title or term quoted verbatim | Retitling or translating the term silently drops it |
+| Substring | a section title, term, or phrase quoted verbatim | Retitling or translating the term silently drops it; reflowing a paragraph wraps the phrase across two physical lines, and a single-line pattern (`[[ … == *"phrase"* ]]`, `grep` without normalization) no longer matches |
 | Quoted original | a check that requires an upstream sentence to appear verbatim | Paraphrasing removes it while preserving meaning |
 
 2. **State facts about an upstream document as observations, not definitions.** A
@@ -74,7 +74,8 @@ now fails on wording whose meaning did not change.
 | Gate anchors on a line count you must change | Update the gate and the document in the same commit, and say so in the PR ([qa-process-acceptance-criteria]) |
 | The failure surfaces in another task's or another agent's check log | Attribute before repairing: identify which file the failing pattern targets, since a cross-file gate makes your edit look like their regression |
 | The gate is genuinely wrong (it forbids a correct sentence with no replacement available) | Change the gate, with a control proving it still catches the defect it owns — do not reword a correct document into a worse one |
-| You are authoring the gate rather than the document | This page covers the author's side; gate construction and its controls are a separate concern → [testing-quality-tests-that-cannot-fail] |
+| The gate is green on your machine and red only in CI after a prose edit (macOS-authored bats suites) | Treat the anchor inventory of step 1 as the authoritative local signal, not the test run: under bash ≤4.0 (macOS system bash 3.2) a failing mid-test `[[ ]]` does not fail the test, so the broken anchor passes silently on your platform ([testing-quality-tests-that-cannot-fail]) |
+| You are authoring the gate rather than the document | This page covers the author's side; gate construction and its controls are a separate concern → [testing-quality-tests-that-cannot-fail]. For a phrase anchor specifically, compare whitespace-normalized text (collapse runs of whitespace, then `grep -qF`) so legitimate reflow of the document cannot break the gate |
 
 ## Instead of
 
@@ -84,6 +85,7 @@ now fails on wording whose meaning did not change.
 | Write "X defines/mandates two variants" when describing an upstream contract | Write the observable shape: "the table has two rows and no Y row" | A vocabulary gate cannot separate describing from redefining, so the defining verb fails a sentence whose content is correct |
 | Run an audit pattern over the whole document that quotes it | Bound it to the normative region by heading range or line range | The quotation is a match, so the whole-file run measures the document's prose about itself |
 | Record "grep found 0 hits" as the audit result | Record the scoped condition that must hold ("no hits outside §Audit") | The bare count is true only for the file revision that produced it and silently becomes false on the next edit |
+| Reflow or rewrap a paragraph a gate quotes as a phrase | Keep each asserted phrase on one physical line, or switch that gate to whitespace-normalized comparison in the same commit | A single-line substring anchor breaks at any wrap point inside the phrase, and on macOS bats the breakage is locally invisible (bash ≤4.0 `[[ ]]` gap) |
 
 ## Sources
 
@@ -91,6 +93,8 @@ now fails on wording whose meaning did not change.
 - https://docs.vale.sh/topics/scopes.md — scopes restrict where a rule applies via markup-aware selectors; "Any scope prefaced with `~` is negated" and scopes can be chained, so checks can be kept off regions like code examples
 - https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md — rules expose `code_blocks`, `tables`, `headings` booleans (default `true`) so quoted code can be excluded from a prose rule
 - https://man7.org/linux/man-pages/man1/pgrep.1.html — "The running pgrep, pkill, or pidwait process will never report itself as a match" — self-exclusion is designed in because self-matching is the expected failure
+- Measured 2026-08-14 (macOS bash 3.2.57): `[[ "$s" == *"return to step 1"* ]]` does not match when `$s` carries the phrase split across a newline — the wrap genuinely breaks the anchor on every platform; and `set -e; [[ 1 -eq 2 ]]; echo REACHED` prints, so the broken mid-test anchor is invisible under macOS bats while bash ≥4.2 CI fails it
+- Field reproduction ×2 (dev-loop): PR #94 §O3 and PR #102 — reflowing SKILL.md prose split `return to step 1 of the dispatch` across two lines; `tests/orchestrate-review-pass.bats` asserted it as a single-line substring, CI red on ubuntu only, fixed by reflowing the phrase onto one physical line (commit 9cbc065)
 
 ## Field context
 
diff --git a/wiki/qa/index.md b/wiki/qa/index.md
index be96aca..fbe5a43 100644
--- a/wiki/qa/index.md
+++ b/wiki/qa/index.md
@@ -30,7 +30,7 @@ Match your situation to a "load when" line; load only matching pages.
 | Page | Load when |
 |------|-----------|
 | [spec-document-gates](document-verification/spec-document-gates.md) | Deciding whether passing a doc gate is enough to accept the deliverable: a document passed its checklist but the requirement is still unmet; choosing what the gate must assert beyond keyword presence (table structure, MUST-vs-SHOULD demotion, closed-set completeness, cross-section consistency); setting the release policy a gate verdict feeds (authoring or validating the check code itself → wiki/testing/quality/spec-artifact-checks.md, wiki/testing/quality/checks-that-cannot-pass.md) |
-| [editing-a-gated-document](document-verification/editing-a-gated-document.md) | Editing or rewording a document that grep/regex gates or a lint config check; a gate fails on wording whose meaning did not change; describing what an upstream spec says without tripping a "do not redefine it" gate; a check matches the pattern your own document quotes; recording an audit verdict inside the document that was audited; deciding which checks to re-run after editing a gated document |
+| [editing-a-gated-document](document-verification/editing-a-gated-document.md) | Editing or rewording a document that grep/regex gates or a lint config check; a gate fails on wording whose meaning did not change; reflowing prose a test asserts as a verbatim phrase (CI red on one platform only); describing what an upstream spec says without tripping a "do not redefine it" gate; a check matches the pattern your own document quotes; recording an audit verdict inside the document that was audited; deciding which checks to re-run after editing a gated document |
 
 ## environments
 
diff --git a/wiki/testing/data/test-data-and-isolation.md b/wiki/testing/data/test-data-and-isolation.md
index 0a0171b..546eee4 100644
--- a/wiki/testing/data/test-data-and-isolation.md
+++ b/wiki/testing/data/test-data-and-isolation.md
@@ -10,8 +10,8 @@ sources:
   - https://testing.googleblog.com/2017/01/testing-on-toilet-keep-cause-and-effect.html
   - https://nodejs.org/api/fs.html
   - https://pubs.opengroup.org/onlinepubs/9699919799/utilities/env.html
-last_verified: 2026-08-05
-related: [testing-flaky-diagnosing-flaky-tests, testing-strategy-test-level-choice, testing-strategy-import-time-side-effects, testing-data-artifact-leakage-from-a-suite, testing-quality-behavior-not-implementation, platforms-filesystems-permissions-and-exec-bits, backend-common-change-impact-call-site-enumeration]
+last_verified: 2026-08-14
+related: [testing-flaky-diagnosing-flaky-tests, testing-strategy-test-level-choice, testing-strategy-import-time-side-effects, testing-data-artifact-leakage-from-a-suite, testing-quality-behavior-not-implementation, platforms-filesystems-permissions-and-exec-bits, backend-common-change-impact-call-site-enumeration, infrastructure-agent-orchestration-shared-run-state]
 ---
 
 # Owning Test Data and Isolating Test State
@@ -47,6 +47,7 @@ state-leak symptom.
 | Code under test derives a write path from the environment (`~/...`, `$HOME`, `$XDG_CONFIG_HOME`, `%APPDATA%`) and would touch the real machine | Point that environment variable at a per-test scratch directory in setup and restore it in `finally`; the production path expression then resolves inside the scratch tree with no signature change. Assert afterwards that the real location gained no files |
 | A case whose behavior depends on a variable being **absent** (`run env VAR=x cmd`, `subprocess(env={...})`) | `unset` it in setup — `env` merges into the inherited environment unless given `-i`, so running the suite from a session that exports it silently flips that case to the opposite branch; CI's clean environment stays green and hides it |
 | A fixture file must carry the executable bit (permission checks, PATH/binary-resolution code) | Create it with the mode set at creation time (`writeFileSync(p, body, { mode: 0o755 })`, `open` with a mode) inside a per-test directory under an already-gitignored build-output path of the repo, and remove it in teardown |
+| The suite runs inside a session that a harness/orchestrator injected coordination variables into (run id, status-directory path, task id), and the code under test reads them | `unset` every injected variable in setup and pass state paths to the code under test explicitly as per-test tempdir arguments — the inherited values both flip env-dependent branches against the unset-env baseline and point the tests' writes at the live run's shared state |
 
 4. Keep fixture data **minimal**: create only the entities the behavior under
    test reads. Every extra row is a value a reader must rule out and a
@@ -64,6 +65,7 @@ state-leak symptom.
 | The executable fixture is rewritten between tests | Delete and recreate it: a write to an existing path keeps the original mode, so a second write with a different mode leaves the first one in place (measured on Node v25.8.1) |
 | The machine runs endpoint security (EDR) that flags an executable created under the system temp directory | Keep the fixture inside the repo's gitignored build-output tree and set the bit at creation; that path is what a "+x file dropped in a temp dir" heuristic looks for, and the fixture only needs the bit, not the location ([platforms-filesystems-permissions-and-exec-bits]) |
 | Leftover test artifacts (temp dirs/files) accumulate in the repo and the producers look diffuse | Count leftovers by name prefix (`ls \| sed 's/-[a-z0-9]*$//' \| sort \| uniq -c`) and match the distribution against the sites that create such files — a match closes the attribution; fix those sites, then enforce the cleanup convention with a static check proven red against the unfixed code first |
+| The code under test is the harness that spawned the session now running its suite (an orchestration worker runs the orchestrator's own tests in its worktree) | Treat the leak as two failures: reproduce the test failures with `env VAR=… bats <file>` on a clean checkout to confirm the mechanism, then check the live run's state files for writes stamped with test-fixture values — a leaked state path corrupts the running orchestration ([infrastructure-agent-orchestration-shared-run-state]), which surfaces later as a watcher monitoring the wrong session |
 
 ## Instead of
 
@@ -83,3 +85,4 @@ state-leak symptom.
 - https://abseil.io/resources/swe-book/html/ch12.html — a test is complete when "its body contains all of the information a reader needs in order to understand how it arrives at its result"; prefer DAMP over DRY, and where a helper is used, give it "descriptive parameters that make dependencies explicit" rather than reusing shared constants
 - https://testing.googleblog.com/2017/01/testing-on-toilet-keep-cause-and-effect.html — keep the inputs a test's result depends on visible in the test method instead of in shared setup, so the cause-and-effect relationship is readable without jumping elsewhere
 - Field incident 2026-08-04 (`linkly-t1-repo-policy`, Python): `rows_for(doc)` seeded its rows from the module constant `PAYLOAD` while its tests ran payload `{}`; a shape-only migration of the helper fixed 1 of 11 failures, and moving the payload into the helper's signature fixed 11 of 11
+- Field incident 2026-08-14 (dev-loop issue #100): `launch-session.sh` exports `LO_RUN_ID`/`LO_STATUS_DIR`/`LO_TASK_ID` into every worker session; a worker running `bats tests/launch-session.bats` inherited them — 6 deterministic failures absent on a clean shell, reproduced with `env LO_RUN_ID=… bats`, and the live run's `t90.json` status file was found rewritten with bats tempdir paths and a foreign session name
diff --git a/wiki/testing/index.md b/wiki/testing/index.md
index 6b26016..952afdf 100644
--- a/wiki/testing/index.md
+++ b/wiki/testing/index.md
@@ -40,7 +40,7 @@ Match your situation to a "load when" line; load only matching pages.
 | Page | Load when |
 |------|-----------|
 | [artifact-leakage-from-a-suite](data/artifact-leakage-from-a-suite.md) | Temp directories, build outputs, or scratch files pile up in the repo or system temp after a suite runs; a clone grows with no obvious owner; you suspect the leak comes from everywhere and need a way to locate it; deciding between per-site cleanup, the runner's owned-temp API, and a static rule that enforces the convention |
-| [test-data-and-isolation](data/test-data-and-isolation.md) | Tests need fixture data and you are choosing how to create it; tests pass alone but fail together (or vice versa); DB cleanup, shared fixtures, time-dependent logic, or unique-value collisions |
+| [test-data-and-isolation](data/test-data-and-isolation.md) | Tests need fixture data and you are choosing how to create it; tests pass alone but fail together (or vice versa); DB cleanup, shared fixtures, time-dependent logic, or unique-value collisions; a suite behaves differently inside a harness-spawned session that injects env vars |
 
 ## mocking