knowledge: 10 insights — write-time limit guards must admit shrinking writes, project-local layer over shared agent guidance (2 new pages, 4 pending-duplicate drops of #207, 3 project-specific drops)

log.md

@@ -105,3 +105,4 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest|revise|lint|gap|contradiction|drif
 ## [2026-09-03] ingest | databases/selection — new category: datastore selection by workload (4 pages: choosing-a-datastore-by-workload, relational-jsonb-vs-document-store, vector-search-engine-selection, graph-workloads-relational-vs-graph-db); brave-search research, sources cited per page
 ## [2026-09-04] ingest | infrastructure/agent-orchestration/code-graph-as-orientation-layer (field-tested — 1 new page). A locally built code knowledge graph (graphify) is a freshness-gated, lead-not-evidence orientation layer for planning and parallel task decomposition: gate on graph mtime vs git log, symbol-anchored explain/path only, CLI delivery with bounded output, graph-derived assumptions named in reports. Sources: Developers Digest, AQ Score, Autonoma, Tiare Balbi, graphify README + measurements on graphifyy 0.4.23.
 ## [2026-09-16] ingest | knowledge-flush of the harvested insight queue — 2 new pages, 3 amended pages, 2 domain indexes updated; 4 of 4 claimed candidates ingested, 0 dropped. New: testing/quality/precedence-between-competing-exit-conditions (verified — a test claiming one exit condition beats another must stage the competing condition to become true in the same iteration the condition under test reaches its threshold, derive that iteration from the threshold rather than a literal, prove the assertion by swapping the two source blocks and requiring exactly that test to redden, and assert the loser's side effect did not run; grounded in the mutation-testing infection condition — Vera-Pérez et al. 2019, "the test inputs are not sufficient to infect the state of the program" — plus PIT's per-test kill attribution, with the dev-loop watch-status.sh R6 precedence case as the field measurement), infrastructure/agent-orchestration/escape-hatch-uses-as-a-knowledge-gap-signal (field-tested — a grounding gate's escape hatch is the only place that knows a decision had no source, so the gate emits one gap-queue row at the point it grants the pass, with the decision text, an enumerated reason separating "no page exists" from "page exists but was not found", and a periodic reconciliation of hatch uses against queue rows; the hatch keeps passing. GitHub code scanning's dismissal flow cited as the canonical recorded-hatch shape — mandatory reason, comment on the alert timeline, `dismissed_comment` on the API, reviewable Closed list. Measured locally: plan-gate.sh:166 passes `[no-wiki]` with a bare `continue` while SKILL.md:135 asks in prose for an ingest candidate — 276 non-index pages, exactly one `gap` entry in this log). Amended: infrastructure/agent-orchestration/pane-delivery-confirmation +Do-this #6 / +1 edge row / +1 Instead-of row (skip the pane check entirely on an iteration that sent keys — the pane repaints only after the target consumes the input, so a same-iteration capture can confirm the very state the send just cleared; reproduced 2026-09-16 on tmux/macOS, where a 0.4s-working command left the same-iteration capture reading the stale witness while an instant command repainted in time, making the outcome a function of the target's work time), platforms/processes/driving-a-tui-in-a-tmux-pane +1 edge row pointing at that rule, infrastructure/agent-orchestration/code-graph-as-orientation-layer +2 edge rows and +2 sources (graphifyy 0.4.23 installs post-commit and post-checkout only, while `git pull` runs post-merge — reproduced on git 2.50.1: fast-forward pull and merge-commit pull both fired post-merge alone, a merge commit fired no post-commit, and a fresh clone carried no hooks at all — so "PR merged upstream, then pull" leaves the graph stale with hooks reporting installed; freshness gate stays mandatory, add a post-merge hook, and build from a workspace scan after a clone). Reciprocal related links added both ways (tests-that-cannot-fail, policy-at-several-return-sites, completion-predicates; session-completion-gates, autonomous-decision-rulings, spec-document-gates). Structure checks 278 pages / 13 indexes / 0 findings; no prohibition-lint findings on the touched pages.
+## [2026-09-17] ingest | knowledge-flush of the harvested insight queue — 2 new pages, 2 domain indexes updated; 3 of 10 claimed candidates ingested, 3 dropped as project-specific, 4 dropped as pending duplicates of #207. New: infrastructure-ci-cd-write-time-limit-guards (verified — deny a limit-enforcing write only when the result exceeds the limit AND grew, so an over-limit state can still be shrunk; Kubernetes quota delta admission, CRD validation ratcheting, ESLint bulk suppressions), backend-common-llm-project-local-layer-over-shared-guidance (field-tested — fixed conventional path for a project-local guidance layer; local wins on the same trigger while the shared entry stays loaded; Codex AGENTS.md, git-config, EditorConfig)

wiki/backend/common/change-impact/corpus-sweep-before-a-rejection-rule.md

@@ -9,7 +9,7 @@ sources:
   - https://github.com/rust-lang/rust-clippy/blob/master/lintcheck/README.md
   - https://github.com/rust-lang/crater
 last_verified: 2026-08-07
-related: [backend-common-change-impact-call-site-enumeration, backend-common-api-design-unenforced-declarations, testing-quality-guard-shape-vs-consequence, qa-process-regression-scope]
+related: [backend-common-change-impact-call-site-enumeration, backend-common-api-design-unenforced-declarations, testing-quality-guard-shape-vs-consequence, qa-process-regression-scope, infrastructure-ci-cd-write-time-limit-guards]
 ---
 
 # Bounding a New Rejection Rule Against the Existing Corpus

wiki/backend/common/llm/binding-instructions-for-agents.md

@@ -8,7 +8,7 @@ sources:
   - https://github.com/obra/superpowers
   - https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md
 last_verified: 2026-08-24
-related: [backend-common-api-design-agent-tool-granularity, backend-common-llm-progressive-disclosure-artifacts]
+related: [backend-common-api-design-agent-tool-granularity, backend-common-llm-progressive-disclosure-artifacts, backend-common-llm-project-local-layer-over-shared-guidance]
 ---
 
 # Instruction Text That Must Bind an LLM Agent's Behavior

wiki/backend/common/llm/progressive-disclosure-artifacts.md

@@ -8,7 +8,7 @@ sources:
   - https://github.com/virgiliojr94/book-to-skill
   - https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md
 last_verified: 2026-08-24
-related: [backend-common-llm-binding-instructions-for-agents, backend-common-llm-context-window-budget]
+related: [backend-common-llm-binding-instructions-for-agents, backend-common-llm-context-window-budget, backend-common-llm-project-local-layer-over-shared-guidance]
 ---
 
 # Splitting a Large Knowledge Artifact an Agent Loads On Demand

wiki/backend/common/llm/project-local-layer-over-shared-guidance.md

@@ -0,0 +1,76 @@
+---
+id: backend-common-llm-project-local-layer-over-shared-guidance
+domain: backend
+category: llm
+applies_to: [general]
+confidence: field-tested
+sources:
+  - https://developers.openai.com/codex/guides/agents-md
+  - https://git-scm.com/docs/git-config
+  - https://spec.editorconfig.org/
+last_verified: 2026-09-17
+related: [backend-common-llm-binding-instructions-for-agents, backend-common-llm-progressive-disclosure-artifacts, infrastructure-config-environment-config]
+---
+
+# Adding a Project-Local Layer Over Shared Agent Guidance
+
+## When this applies
+
+A shared, versioned body of agent guidance (a bundled wiki, a plugin's rule
+set, global instructions) serves many repositories, and one repository needs
+entries that apply only to it. You are deciding where that project layer lives,
+how a consumer finds it, and which layer applies when both match the same
+trigger.
+
+## Do this
+
+1. **Give the local layer one fixed, conventional path under the project root
+   and commit it with the project.** Every consumer — router, linter, gate,
+   test — derives the path by the same rule with nothing to resolve. Git
+   (`$GIT_DIR/config`), EditorConfig (`.editorconfig`) and Codex (`AGENTS.md`
+   per directory) all locate their project layer by fixed name.
+
+2. **Resolve a same-trigger match as: local directives apply, shared entries
+   stay loaded for what the local entry does not cover.** Read the shared layer
+   first and the local layer last, so the local value is the one in effect for
+   each key both define. All three tools above implement this order.
+
+3. **Decide the tie by layer, then by specificity.** A local edge-case row
+   overrides a shared general rule; within one layer, keep the existing
+   most-specific-match rule.
+
+4. **Make the local entry a delta.** It states what differs in this project and
+   leaves the rest to the shared entry, so a shared-layer update still reaches
+   the project for everything the delta does not name.
+
+| Case | Do |
+|------|----|
+| Only the shared layer matches | Apply it unchanged |
+| Only the local layer matches | Apply it; no shared lookup is required |
+| Both match, directives agree | Apply both; the local entry adds project detail |
+| Both match, directives disagree | Apply the local directive for the disagreeing point and the shared entry for every other point |
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| The path rule would read an environment variable set by the agent harness | Derive the root from the script's own location or an argument instead: a harness variable present in hook processes can be unset in the agent's shell commands and in the test runner, so production takes a fallback branch the tests never ran |
+| The natural home is a tool-state directory that is git-ignored | Place the layer outside it; committing one subdirectory of an ignored tree needs a split ignore pattern that contradicts the "this directory is workspace state" rule readers rely on |
+| A local entry fully replaces the shared one for this project | Say so in the local entry's first line; Codex models this as a separate `AGENTS.override.md` that is used instead of `AGENTS.md` at that level |
+| The project has nested sub-projects | Closer layers win: Codex concatenates "from the root down", EditorConfig reads the closer file last |
+| A local entry would be correct in any repository | It belongs in the shared layer; move it upstream and delete the local copy |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Add a config key or env var that relocates the local layer | Fix the path by convention | Each knob is a resolution step every gate, linter and router must reproduce identically; one that skips it reads a different layer |
+| Load only the local entry when both layers match | Load both, local last | The project never restated the shared coverage, so dropping the shared entry drops guidance nobody decided to remove |
+| Resolve local-vs-shared ties by specificity alone | Layer first, specificity second | Two equally specific entries in different layers stay undecided under a specificity-only rule |
+
+## Sources
+
+- https://developers.openai.com/codex/guides/agents-md — "By layering global guidance with project-specific overrides…"; "Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt."; `AGENTS.override.md` is checked before `AGENTS.md` and "Codex includes at most one file per directory" (page text read 2026-09-17)
+- https://git-scm.com/docs/git-config — system, global, then repository files: "The files are read in the order given above, with last value found taking precedence over values read earlier."
+- https://spec.editorconfig.org/ — "If multiple EditorConfig files have matching sections, the pairs from the closer EditorConfig file are read last, so pairs in closer files take precedence."
+- Field context 2026-09-17 (`dev-loop` t4-local-layer plan, decisions D1 and D5): a fixed `wiki-local/` under the project root was chosen over a tools-config path knob, a git-ignored state directory, and a `CLAUDE_PROJECT_DIR` read (unset in agent Bash commands and in bats); precedence chosen as local-wins-with-shared-retained over specificity-only and local-only loading. Confidence is `field-tested` because rule 1's no-knob stance, rule 4 and the env-var and ignored-directory rows rest on this planning context alone; the precedence directives (rules 2–3, the decision table, the nested and override rows) are additionally confirmed by the three tool documents above

wiki/backend/index.md

@@ -97,6 +97,7 @@ Match your situation to a "load when" line; load only matching pages.
 | [context-window-budget](common/llm/context-window-budget.md) | Repointing an LLM client or agent CLI at a different model, a self-hosted server (vLLM/Ollama), or a gateway (LiteLLM); setting `max_tokens` for a client whose default was sized for a larger model; the first request after such a switch returns 400 with a context-window error; deciding where to set the cap (request body vs client env var vs gateway config) and how to point the base URL at a proxy; handling truncation that arrives as a normal 200 |
 | [binding-instructions-for-agents](common/llm/binding-instructions-for-agents.md) | Authoring or editing a skill, system prompt, hook message, or CLAUDE.md/AGENTS.md rule that must change an agent's behavior under pressure; an instruction keeps getting rationalized around; choosing between prohibition, recipe, template-slot, and predicate-rule forms; writing a skill's description/trigger line; adding a pre-send self-check to an output-shape rule |
 | [progressive-disclosure-artifacts](common/llm/progressive-disclosure-artifacts.md) | Authoring a skill or reference bundle that packages a large corpus (a book, manual, wiki) for an agent to consult on demand; an always-loaded skill file grew past a few thousand tokens; sizing per-chunk token budgets by content type and usage depth; an agent Reads an entire large source file to answer narrow questions |
+| [project-local-layer-over-shared-guidance](common/llm/project-local-layer-over-shared-guidance.md) | A shared body of agent guidance (bundled wiki, plugin rule set, global instructions) serves many repositories and one repository needs entries that apply only to it; deciding where the project layer lives and how consumers find it; both a local and a shared entry match the same trigger and you are deciding which applies |
 
 ### ml
 

wiki/infrastructure/agent-orchestration/session-completion-gates.md

@@ -8,7 +8,7 @@ sources:
   - https://code.claude.com/docs/en/hooks
   - https://csf.tools/reference/nist-sp-800-53/r5/ac/ac-5/
 last_verified: 2026-08-13
-related: [infrastructure-agent-orchestration-pane-delivery-confirmation, infrastructure-agent-orchestration-worktree-isolated-workers, platforms-processes-tool-diagnostics-without-a-failing-exit-code, infrastructure-agent-orchestration-dispatching-after-a-completion-report, infrastructure-agent-orchestration-escape-hatch-uses-as-a-knowledge-gap-signal]
+related: [infrastructure-agent-orchestration-pane-delivery-confirmation, infrastructure-agent-orchestration-worktree-isolated-workers, platforms-processes-tool-diagnostics-without-a-failing-exit-code, infrastructure-agent-orchestration-dispatching-after-a-completion-report, infrastructure-agent-orchestration-escape-hatch-uses-as-a-knowledge-gap-signal, infrastructure-ci-cd-write-time-limit-guards]
 ---
 
 # A Gate That Blocks a Worker Session from Ending Mid-Workflow

wiki/infrastructure/ci-cd/changed-files-only-gates.md

@@ -19,6 +19,7 @@ related:
     testing-quality-harness-reverse-controls,
     platforms-shells-portable-shell-scripts,
     testing-quality-history-dependent-checks-on-shallow-clones,
+    infrastructure-ci-cd-write-time-limit-guards,
   ]
 ---