Skip to content

knowledge: keg-only PATH + double-quote backslash (2 verified platforms insights) #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
choiyounggi wants to merge 1 commit into from
Closed

knowledge: keg-only PATH + double-quote backslash (2 verified platforms insights) #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 97 additions & 83 deletions .dev-loop/INGEST_REPORT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,95 +1,109 @@
# Consolidated review — knowledge PRs #6–#13
# Knowledge flush — 3 insight(s): 2 ingested, 1 held back

Eight fork PRs (`dch0202-rsquare`, 2026-07-28 → 2026-08-02) were reviewed together
against `AGENTS.md`. Each PR was audited by an independent reviewer (format rules,
sources, vague-qualifier ban, ≤120 body lines, index/log invariants), then
cross-compared to catch duplication the per-PR flushes could not see — they branched
independently off the same main and rewrote the same shared index/log files. Fork
branches can't be edited from here and several PRs needed content changes (drop a
duplicate, merge a colliding page), so this branch carries the reconciled end-state
rather than merging each PR as-is (which would import the duplicates).
Drained 3 pending candidates from `~/.dev-loop/queue`. Two were verified and
merged into existing `platforms` pages; one (MLIR IRDL) is verified-but-niche and
held back from this general wiki with a recommendation (see Routing decision).

## Verified best-practice

Sources are per-page and were live-verified in each originating PR's flush; the
independent re-reviews re-checked them. Landed pages and their evidence base:
### 1. Homebrew keg-only formulae are installed but off `PATH` → `verified`
- **Claim:** On macOS, `which <tool>` / `command -v <tool>` reporting not-found
does **not** mean the tool is absent. Homebrew keg-only formulae (llvm, curl,
openjdk, node@N, libpq, ruby) are installed into the Cellar but deliberately not
symlinked onto `PATH`. Check the package manager's record before concluding
absence.
- **Sources checked:** https://docs.brew.sh/FAQ ("What does keg-only mean?" —
"installed only into the Cellar and is not linked into the default prefix");
`brew info llvm` output ("llvm is keg-only, which means it was not symlinked
into /opt/homebrew").
- **How verified (reproduced on this machine, 2026-08-04):** `which mlir-opt` →
"mlir-opt not found" (exit 1) and `command -v mlir-opt` → not found, **while**
`brew list --versions llvm` → `llvm 22.1.8` and
`/opt/homebrew/opt/llvm/bin/mlir-opt --version` → "Homebrew LLVM version
22.1.8". This is the exact incident from the queue (issue #7 deferred on a stale
`which` check though LLVM 22.1.8 was installed).
- **Confidence: verified** (official doc + local reproduction).

| Page | Confidence | Source basis |
|------|-----------|--------------|
| backend/common/llm/completion-response-validation | verified | OpenAI reasoning guide + chat `object` spec (5 `finish_reason` values), vLLM/LiteLLM reasoning fields; field incident (200/`length`/empty content/8,173-char reasoning) |
| backend/common/llm/context-window-budget | verified | Claude context-window docs, LiteLLM exception mapping, vLLM/Claude Code env-var docs |
| backend/common/integrations/externally-owned-defaults | verified | OpenAI deprecations (notice windows) + models `list`, LiteLLM model_discovery; field incident (alias removed between PR verify and review → 400) |
| backend/common/storage/object-key-persistence | verified | AWS S3 CompleteMultipartUpload + managed-upload API/source, aws-sdk-js issues #1158/#5656 |
| infrastructure/containers/host-cgroup-visibility | field-tested | cgroup_namespaces(7), Docker `--cgroupns=host`, nsenter, k8s #103363; OrbStack repro |
| infrastructure/observability/missing-container-metrics | verified/field-tested | k8s resource-metrics-pipeline docs, kube-prometheus-stack values, kubernetes-mixin; OrbStack #2217 repro |
| platforms/environment/unicode-text-matching | verified | UAX #15, Unicode core §3.12, APFS FAQ, POSIX grep; local repro (macOS 15/APFS, grep 2.6.0-FreeBSD, Python 3.13) |
| platforms/shells/command-text-inspected-before-execution | verified | Claude Code hooks docs, POSIX shell §2.6; local reproduction |
| platforms/processes/non-interactive-cli-invocation | verified | GNU nohup, OpenBSD ssh/ssh_config, git, timeout man pages; no-request-in-gateway-log field incident |
| qa/document-verification/spec-document-gates | field-tested | ESLint, Google mutation testing, RFC 2119, Vale, markdownlint; 32/32 mutant / 62/62 intact RFC sessions |
| qa/document-verification/editing-a-gated-document | field-tested | pgrep, Vale, markdownlint; in-house editing methodology |
| testing/quality/checks-that-cannot-pass | verified | James Shore AoAD2, POSIX grep exit status, Semgrep rule-testing, pytest exit codes; BSD/ugrep measurement |
| testing/quality/spec-artifact-checks | verified | JSON Schema, ESLint RuleTester, pitest, GFM table spec; local cell-count repro + GitHub renderer cross-check |
| testing/quality/harness-reverse-controls | verified | mutation-testing + CI-control sources; field repro (re-fetched all cited URLs, PASS) |
### 2. Bash double-quote strips the backslash only before five chars → `verified`
- **Claim:** Inside a double-quoted bash string, the backslash retains special
meaning only before `$`, backtick, `"`, `\`, or newline. So a regex embedded in
a double-quoted string has `"\$"` collapse to a bare `$` (a regex end-of-line
anchor) before the tool ever sees it, while `"\d"` keeps its backslash. Miscopy
the pattern as `$` or `\\$` and the EOL match silently changes.
- **Sources checked:**
https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html — the
backslash "retains its special meaning only when followed by one of" `$`,
backtick, `"`, `\`, or newline (page fetched and the sentence confirmed present
2026-08-04).
- **How verified (reproduced 2026-08-04):** `od -c` on the guardrails-style
pattern `"(sh|bash)([[:space:]]|-|<|\$)"` shows the byte reaching grep is a bare
`$` (backslash stripped); `echo 'curl http://x | sh' | grep -E "$pat"` matches
`sh` at end-of-line, confirming `$` acts as the EOL anchor. Matches the queue
incident (why `curl … | sh` with no trailing char matches the bash-guard rule).
- **Confidence: verified** (official doc + local reproduction).

Three pages were reconciled from two overlapping PR versions each, keeping the more
complete/better-sourced body and folding in the other's unique cases:
- **completion-response-validation** — #12 body (all five `finish_reason` values,
`tool_calls`/`function_call` carve-out, streaming, Responses API, "reasoning is
scratch, not deliverable") kept in `llm/` (coherent with #6/#13); folded in #6's
DeepSeek first-party edge + the field incident.
- **externally-owned-defaults** — #12 generalized body (any repo-external resource)
in `integrations/`; folded in #6's alias-removed field incident + the
gateway-config-vs-live-upstream nuance.
- **non-interactive-cli-invocation** — #12 body (GNU-nohup extension precision,
ssh -n stdin-detach vs BatchMode, pre-log DNS/TLS/proxy + `curl -v`) kept; folded
in #11's DEBIAN_FRONTEND, pager/color TTY case, wrapper-CLI case, field incident.
### 3. MLIR IRDL region ops fail verification without a borrowed terminator → `field-tested`
- **Claim:** An MLIR op with a region defined declaratively via IRDL (LLVM 22)
fails block verification ("block with no terminator") because IRDL cannot
declare a terminator op or attach `NoTerminator`/set `RegionKind` on
user-defined ops. Either embed a borrowed terminator
(`omp.terminator`/`llvm.unreachable`) or model the nesting with flat marker ops
carrying a `children` id-list attribute.
- **Sources checked:** https://mlir.llvm.org/docs/LangRef/ (SSACFG regions require
a terminator; a single-block region may opt out only via `NoTerminator` **on the
enclosing op**); https://mlir.llvm.org/docs/Dialects/IRDL/ (`irdl.dialect`
itself carries `NoTerminator`, but the op-definition surface exposes no way to
attach that trait or set `RegionKind` on the ops you define). The mechanics are
doc-corroborated; the specific IRDL limitation is not stated as such in the docs.
- **How verified:** contributor measured it with `mlir-opt 22.1.8` (region op →
"block with no terminator"; only `omp.terminator`/`llvm.unreachable` verified
inside a generic IRDL region; flat marker ops round-tripped cleanly). Not
re-reproduced here (no dialect fixture on hand).
- **Confidence: field-tested** — measured in production, mechanism doc-backed, but
the IRDL-can't-set-it limitation has no official-doc statement.

## Existing-layer check

Cross-PR and against-main duplication was the focus. Findings and resolutions:

- **spec-artifact-checks (#8) ≡ document-conformance-checks (#9)** — same case
(coverage-vs-validity split, per-check negative controls, GFM pipe parsing,
ESLint/Semgrep/mutation examples). #9's report predated awareness of #8. →
**#8 kept canonical; #9's page dropped, `testing/docs-as-spec` category not created.**
- **completion-response-validation (#6) ≈ llm-response-completeness (#12)** — ~95%
same case (HTTP 200 ≠ usable output; `length`/blank/reasoning-budget). →
**merged into one `llm/` page; #12's `integrations/` copy dropped.**
- **gateway-model-alias-defaults (#6) ≈ externally-owned-defaults (#12)** — ~80%;
#12 generalizes the model-alias case to any external resource. →
**kept the general `integrations/` page; #6's LLM-only page dropped.**
- **non-interactive-cli-invocation** — created by BOTH #11 and #12 (file collision).
→ **single reconciled page.**
- Distinct (no overlap, all landed): checks-that-cannot-pass, harness-reverse-controls,
spec-document-gates, editing-a-gated-document, unicode-text-matching,
command-text-inspected-before-execution, object-key-persistence, context-window-budget,
host-cgroup-visibility, missing-container-metrics.
- Reciprocal `related:` links added on existing pages (tests-that-cannot-fail,
timeouts-and-retries, environment-config, release-gates, background-services,
portable-shell-scripts, timezone-and-locale, paths-case-and-line-endings,
acceptance-criteria, resource-limits-and-probes, logs-metrics-signals,
minimum-case-set). A dropped-page backlink (#6 → gateway-model-alias-defaults on
environment-config and release-gates) was retargeted to externally-owned-defaults.
- Invariants verified programmatically: all `related:`/inline `[id]` references
resolve, every page listed in its domain index, no duplicate ids, no page >120
body lines.
- **Insight 1 → `wiki/platforms/environment/path-resolution.md` (merge, not new).**
Read the full page. Its "load when" line already owns "'command not found'
though the tool is installed"; it already had a brew-shadowing row and a
`which`→`type`/`command -v` Instead-of row. **Gap:** none of those cover the
keg-only case where even `command -v`/`type` correctly report not-found because
the binary is genuinely unlinked (absence-on-PATH ≠ not-installed). Merged one
`Edge cases` row + one `Instead of` row + one source; no duplication, no
conflict. Related links already point to `toolchains/version-management` and
`processes/background-services` (both relevant, left as-is).
- **Insight 3 → `wiki/platforms/shells/portable-shell-scripts.md` (merge, not new).**
Read the full page plus the adjacent
`shells/command-text-inspected-before-execution.md` (the candidate arose in a
guardrails PreToolUse hook, which that page owns). That page is about a *gate
reading command text*; this lesson is about the *shell mangling an embedded
regex* — a quoting-semantics fact, so it belongs on portable-shell-scripts (the
quoting page), which the two pages already cross-link via `related:`. The page's
"Do this #2" says "quote every expansion" but nowhere states the double-quote
backslash-stripping rule. Merged one `Edge cases` row + one `Instead of` row +
one source; no duplication, no conflict.
- **Insight 2 (MLIR IRDL):** no domain owns compiler/dialect internals. Closest
seeded categories (`platforms/toolchains` = version pinning; `infrastructure`
= CI/CD) genuinely do not cover "how MLIR's region verifier interacts with
IRDL-defined ops." No merge target exists.

## Routing decision

- `backend/common/llm/` (new) — LLM-specific server concerns: completion-response-validation,
context-window-budget. Coherent home shared by #6 and #13.
- `backend/common/integrations/` (new) — general repo-external-dependency concern:
externally-owned-defaults. Kept separate from `llm/` because its scope is any
external resource (bucket/queue/index), not LLM-only.
- `backend/common/storage/` (new) — object-key-persistence.
- `qa/document-verification/` (new) — spec-document-gates, editing-a-gated-document.
Introduced by both #10 and #11; unified into one index section.
- `testing/quality/` (existing) — checks-that-cannot-pass, spec-artifact-checks,
harness-reverse-controls (test/check-authoring discipline, distinct from
qa/document-verification which is release-process gate design).
- `platforms/{environment,shells,processes}/` (existing) — unicode-text-matching,
command-text-inspected-before-execution, non-interactive-cli-invocation.
- `infrastructure/{containers,observability}/` (existing) — host-cgroup-visibility,
missing-container-metrics.

Source PRs #6–#13 are closed with a disposition comment crediting the author.
- **Insight 1 → `platforms/environment/path-resolution`** (merged). The harvested
`domain: infrastructure` hint was wrong — this is a PATH-resolution symptom, not
a CI/CD/build concern. No new category.
- **Insight 3 → `platforms/shells/portable-shell-scripts`** (merged). The harvested
`domain: security` hint was incidental (the bug surfaced in a guardrails hook);
the reusable lesson is bash double-quote semantics, owned by `platforms/shells`.
No new category.
- **Insight 2 → held back (no ingest).** Verified-as-field-tested and genuinely
correct, but it is single-repo compiler-internals with no home in the current 10
general SWE domains. Ingesting it would mean creating a `compilers`/`mlir` domain
for one insight loadable by exactly one repo — which the wiki's own philosophy
(one case per page, cross-repo reusability) argues against. **Recommendation:**
keep it in the owning repo's own docs (e.g. a dialect NOTES file), or, if you
want the wiki to carry dialect-authoring knowledge, say so and I will open a
dedicated `compilers` domain in a follow-up. Logged as a `gap` entry in `log.md`.
All 3 candidates are retired from the active queue so auto-flush will not re-run
them; the MLIR row is preserved in `.processed.jsonl` (status `deferred-out-of-scope`).
3 changes: 3 additions & 0 deletions log.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,6 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest|revise|lint|gap|contradiction|drif
## [2026-08-03] ingest | Consolidated review of knowledge PRs #6–#13 (8 fork PRs) into 12 pages. New: backend/common/llm (completion-response-validation, context-window-budget), backend/common/integrations (externally-owned-defaults), backend/common/storage (object-key-persistence), infrastructure/containers/host-cgroup-visibility, infrastructure/observability/missing-container-metrics, platforms/environment/unicode-text-matching, platforms/shells/command-text-inspected-before-execution, platforms/processes/non-interactive-cli-invocation, qa/document-verification (spec-document-gates, editing-a-gated-document), testing/quality (checks-that-cannot-pass, spec-artifact-checks, harness-reverse-controls). All cited URLs are per-PR live-verified; three pages were reconciled from two overlapping PR versions each (see revise/dedup entries below).
## [2026-08-03] revise | Reconciled 3 pages from overlapping PR pairs, taking the more complete/better-sourced body and folding in the other's unique cases: backend/common/llm/completion-response-validation (#12 body — tool_calls/function_call carve-out, streaming, Responses API status==incomplete, "reasoning is scratch, not deliverable" — kept in llm/ per #6/#13 category, folded in #6's DeepSeek-first-party edge + the 8,173-char reasoning_content field incident); backend/common/integrations/externally-owned-defaults (#12 generalized body — any repo-external resource — folded in #6's LiteLLM-alias-removed field incident + gateway-config-vs-live-upstream nuance); platforms/processes/non-interactive-cli-invocation (#12 body — GNU-nohup extension precision, ssh -n stdin-detach vs BatchMode, pre-log DNS/TLS/proxy + curl -v — folded in #11's DEBIAN_FRONTEND, pager/color TTY case, wrapper-CLI case, and the no-request-in-gateway-log field incident).
## [2026-08-03] dedup | Dropped 3 candidate pages as duplicates/superseded during the #6–#13 consolidation: testing/docs-as-spec/document-conformance-checks (#9 — same case as testing/quality/spec-artifact-checks from #8: coverage-vs-validity split, per-check negative controls, GFM pipe parsing; #8 kept as canonical, docs-as-spec category not created); backend/common/llm/gateway-model-alias-defaults (#6 — subsumed by the generalized integrations/externally-owned-defaults; the model-alias case is one instance); backend/common/integrations/llm-response-completeness (#12 — folded into llm/completion-response-validation, kept in llm/ for category coherence with context-window-budget).
## [2026-08-04] revise | platforms/environment/path-resolution +1 edge case + 1 Instead-of row: Homebrew keg-only formulae (llvm, curl, openjdk, node@N…) are installed but deliberately not symlinked onto PATH, so `which`/`command -v` report not-found though the tool is present — check `brew list --versions <formula>` and `"$(brew --prefix <formula>)/bin/"` before concluding absence; invoke via the keg path or `brew link --force`. Doc-backed (docs.brew.sh/FAQ) + reproduced 2026-08-04 (`which mlir-opt`→not-found while llvm 22.1.8 installed at /opt/homebrew/opt/llvm/bin). last_verified bumped to 2026-08-04.
## [2026-08-04] revise | platforms/shells/portable-shell-scripts +1 edge case + 1 Instead-of row: inside double quotes bash strips the backslash only before `$` backtick `"` `\` newline, so a regex embedded in a double-quoted string (`grep -E "…\$"`) reaches the tool with a bare `$` (EOL anchor) while `"\d"` keeps its backslash — single-quote regex literals or account for exactly those five escapes. Doc-backed (GNU Bash manual, Double Quotes) + reproduced 2026-08-04 (guardrails PreToolUse rule `(sh|bash)([[:space:]]|-|<|\$)` matching `curl … | sh` at EOL). last_verified bumped to 2026-08-04.
## [2026-08-04] gap | Held back one queued candidate as out-of-scope for a general cross-repo wiki: MLIR IRDL region ops fail block verification ("block with no terminator") because IRDL (LLVM 22) cannot declare a terminator op or set NoTerminator/RegionKind on user-defined ops, so a region-bearing IRDL op needs a borrowed terminator (omp.terminator/llvm.unreachable) or should use flat marker ops carrying a `children` id-list instead. Field-tested (measured with mlir-opt 22.1.8) and the terminator/NoTerminator/RegionKind mechanics are doc-corroborated (mlir.llvm.org LangRef, IRDL dialect), but it is single-repo compiler-internals with no home in the current 10 general SWE domains. Recommend it live in the owning repo's own docs, or open a dedicated `compilers`/`mlir` domain if the wiki should carry dialect-authoring knowledge.
Loading
Loading