choiyounggi · choiyounggi · Aug 4, 2026
@@ -1,95 +1,99 @@
-# Consolidated review — knowledge PRs #6–#13
+# Knowledge flush — 3 insight(s)
 
-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`, verified each against real
+sources, routed them, and ingested them as 3 new `platforms` pages.
 
 ## 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. Backslash escapes inside a double-quoted shell string holding a regex
+- **Claim:** In a double-quoted shell string, backslash keeps its escape meaning
+  **only** before `$`, `` ` ``, `"`, `\`, and newline; before anything else both
+  characters survive. So `grep -E "…(\$)"` reaches grep as `…($)` — a bare `$`
+  end-of-line anchor — while `"a\.b"` reaches grep as `a\.b` (literal dot).
+- **Sources checked:** POSIX Shell & Utilities 2.2.3 Double-Quotes
+  (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html);
+  GNU Bash manual "Double Quotes"
+  (https://www.gnu.org/software/bash/manual/bash.html#Double-Quotes).
+- **How verified:** Reproduced 2026-08-04 — `printf 'curl x | sh\n' | grep -E
+  "(sh|bash)([[:space:]]|-|<|\$)"` matched end-of-line `sh` (the `\$` reached grep
+  as a `$` anchor); `grep -E "a\.b"` kept `\.` literal (matched `a.b`, not `axb`).
+- **Confidence: verified** (official spec + bash manual + 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. Bump the version when shipping code through a version-keyed plugin cache
+- **Claim:** A Claude Code marketplace plugin (and any tag-pinned artifact cache)
+  keys its cache on the version string; shipping new code under an unchanged
+  `plugin.json`/`marketplace.json` version leaves the version-keyed cache dir
+  (`~/.claude/plugins/cache/<mkt>/<plugin>/<version>/`) unrefreshed, so the code
+  never runs. Bump the version in the same change; clear the cache manually if a
+  known updater bug leaves it stale.
+- **Sources checked:** Claude Code plugin-marketplaces docs
+  (https://code.claude.com/docs/en/plugin-marketplaces); anthropics/claude-code
+  issues #45542 ("cache not refreshed when version number is unchanged"), #17361
+  ("cache never refreshes … reads stale cache"), #61954 ("`plugin update` reports
+  'at latest' while cache stays stale").
+- **How verified:** Local cache observation — `~/.claude/plugins/cache/` holds
+  per-version sibling dirs (`figma/2.2.81|2.2.87|2.2.88`, `dev-loop/0.8.0…0.11.0`),
+  confirming version-string keying; the exact cache path in the issues matches.
+- **Confidence: verified** (official issue tracker + docs + local observation).
+- **Nuance recorded on the page:** the version bump is *necessary*; open updater
+  bugs mean it is sometimes *not sufficient*, so the page adds a manual
+  cache-clear fallback rather than asserting the bump always suffices.
 
-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. Confirm a CLI's `--json` field paths from read-only output before parsing
+- **Claim:** Before writing a parser for another tool's `--json`, run its
+  read-only verbs (`list`/`status`/`show`/`ps`), build extraction only on observed
+  field paths, and pin a captured sample as a test fixture so the parser is
+  CI-testable without the live tool. Guessed field names compile but silently
+  never match; verifying via a state-mutating verb has side effects.
+- **Sources checked:** jq manual (https://man7.org/linux/man-pages/man1/jq.1.html)
+  — a missing key yields `null`; `-e`/`--exit-status` gives a loud nonzero exit on
+  a wrong path (supports the "fail loudly on a missing path" directive).
+- **How verified:** Field incident (2026-08) building `orca-spawn.sh` /
+  `orca-worktree-alive.sh` — orca's read-only `terminal list` and `worktree ps
+  --json` exposed `handle` / `liveTerminalCount` / `hasAttachedPty`, letting both
+  wrappers be built and CI-tested against canned JSON with zero live spawns.
+- **Confidence: field-tested.** The core discipline (verify schema from real
+  output, pin a recorded fixture) is production experience; only the jq
+  failure-mode mechanic is doc-cited, so the page is not marked `verified`.
 
 ## Existing-layer check
 
-Cross-PR and against-main duplication was the focus. Findings and resolutions:
+Routed via `INDEX.md` → `platforms` (all three are OS/tooling-level, not
+application logic). Read the full `wiki/platforms/index.md` plus every page whose
+"load when" overlapped, and `wiki/security/index.md` (insight 1 was harvested with
+a `security` hint) and `wiki/backend/index.md` (insight 3's data-consumption
+angle).
 
-- **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** — read `shells/portable-shell-scripts.md` (owns quoting of
+  *expansions*: word-splitting/globbing) and `shells/command-text-inspected-before-execution.md`
+  (owns a *gate reading* your command). Neither covers escape processing of a
+  regex written as a shell literal, and the trigger ("authoring a pattern literal
+  in a shell string") is distinct → **new page**, not a merge. Added reciprocal
+  `related:` links to both. Rejected the `security` hint: the backslash rule is a
+  uniform shell-parsing mechanic, not a trust-boundary decision.
+- **Insight 2** — no existing page covers plugin/artifact-cache distribution.
+  Closest neighbor is `toolchains/version-management` (pinning versions for
+  reproducibility — the inverse concern); linked as `related`, not merged.
+- **Insight 3** — read `processes/non-interactive-cli-invocation.md` (owns the
+  *hang/prompt/stdin* failure mode of calling a CLI) and
+  `backend/common/integrations/externally-owned-defaults.md` (external resources
+  changing under you). Insight 3 is a distinct trigger (schema-parsing
+  correctness) → **new page**, cross-linked to both. Added a reciprocal
+  `related:` link on non-interactive-cli-invocation.
+
+No conflicts with existing directives found; nothing overwritten; no duplicates —
+all three are new triggers.
 
 ## 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.
+| Insight | Target domain/category/page | New? |
+|---------|-----------------------------|------|
+| 1 | `platforms/shells/escapes-in-shell-string-literals.md` | new page (existing category) |
+| 2 | `platforms/tools/version-keyed-artifact-cache.md` | new page (existing category `tools`) |
+| 3 | `platforms/processes/parsing-cli-structured-output.md` | new page (existing category) |
 
-Source PRs #6–#13 are closed with a disposition comment crediting the author.
+No new categories were created — `shells`, `tools`, and `processes` already exist
+under `platforms` and each cleanly owns its insight. `wiki/platforms/index.md`
+gained one "load when" row per page; `log.md` has the dated ingest entry.
+Lint checks pass: all three bodies ≤120 lines (61/59/54), no banned vague
+qualifiers, every `related:` id resolves.
@@ -37,3 +37,4 @@ 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] ingest | platforms +3 (knowledge-flush, 3 queued insights): shells/escapes-in-shell-string-literals (double-quote backslash retention — `\$`→`$` EOL anchor, single-quote regex literals; POSIX 2.2.3 + bash manual + reproduced), tools/version-keyed-artifact-cache (bump plugin.json+marketplace.json version in the same change or the version-keyed cache dir never refreshes; manual cache clear fallback; Claude Code issues #45542/#17361/#61954 + docs + local cache observation), processes/parsing-cli-structured-output (confirm --json field paths from a read-only verb before parsing, pin a captured fixture for CI; field-tested on orca CLI, jq --exit-status source). Reciprocal related-links added to portable-shell-scripts, command-text-inspected-before-execution, non-interactive-cli-invocation.