@event4u/agent-config 6.1.0 → 7.0.0

package/dist/agent-src/skills/root-cause-frameworks/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: root-cause-frameworks
+description: "Use when tracing the root cause of a resolved incident or recurring bug — 5-whys chain, fishbone categorisation, contributing-factors split — even if the user says 'why does this keep breaking?'."
+source: package
+domain: quality
+model_tier: high
+workspaces:
+  - engineering
+packs:
+  - analysis-workbench
+lifecycle: active
+trust:
+  level: professional
+  confidence: medium
+  human_review_required: false
+install:
+  default: false
+  removable: true
+---
+
+# root-cause-frameworks
+
+> Structured root-cause analysis for resolved incidents and recurring bugs.
+> Sibling of [`systematic-debugging`](../systematic-debugging/SKILL.md) (live
+> reproduction loop) and [`bug-analyzer`](../bug-analyzer/SKILL.md) (static
+> call-site analysis) — this skill takes the post-resolution "why did this
+> happen and how do we stop it recurring?" view.
+
+## When to use
+
+- A resolved incident needs a structured cause investigation before
+  writing the post-mortem.
+- A bug recurs and the team needs to understand the underlying system
+  condition, not just the symptom.
+- Invoked directly or by [`blameless-post-mortem`](../blameless-post-mortem/SKILL.md)
+  to populate the cause section.
+
+Do NOT use when:
+
+- Actively debugging a failing test or unresolved crash — use
+  [`systematic-debugging`](../systematic-debugging/SKILL.md) instead.
+- The goal is to enumerate call-site impact of a change — use
+  [`blast-radius-analyzer`](../blast-radius-analyzer/SKILL.md) instead.
+
+## Procedure
+
+Work through the three methods in order; return the best-supported result.
+
+### 1. 5-Whys chain
+
+Ask "Why did X happen?" iteratively, attaching **evidence** to each
+link. Continue until the link is unfalsifiable, evidence runs out, or
+you reach a systemic condition outside the team's control.
+
+Rules:
+
+- Each link must cite at least one piece of evidence (log line, metric,
+  test failure, code path, human observation). Label unverified links
+  explicitly as `[speculative]`.
+- If a link branches into two independent causes, follow both — a
+  branching chain is common and valid.
+- Stop a branch when: (a) the next Why has no available evidence, or
+  (b) the answer is outside the system boundary (e.g. "the cloud
+  provider had an outage").
+
+### 2. Fishbone / Ishikawa (if chain stalls or branches widely)
+
+When the 5-whys chain stalls before reaching a systemic cause, or
+branches into more than three independent paths, map contributing
+factors across six categories:
+
+| Category | Sample questions |
+|---|---|
+| People | Knowledge gap, on-call fatigue, ambiguous ownership? |
+| Process | Missing review step, deploy gate skipped, alert threshold wrong? |
+| Technology | Library version, configuration drift, race condition, hardware limit? |
+| Data | Unexpected input shape, stale cache, missing validation, schema mismatch? |
+| Environment | Infra difference between environments, dependency version skew? |
+| Communication | Unclear spec, siloed knowledge, delayed escalation? |
+
+List each identified factor as a bullet under its category. A factor
+may appear in more than one category — that is evidence of a systemic
+coupling worth naming.
+
+### 3. Contributing-factors split
+
+Classify every cause surfaced in steps 1–2 into exactly one bucket:
+
+| Bucket | Definition |
+|---|---|
+| `root` | The condition that, if absent, the incident would not have occurred. |
+| `contributing` | A condition that increased likelihood or severity, but not sufficient alone. |
+| `amplifying` | A condition that made recovery slower or harder once the incident started. |
+| `coincidence` | Present at the time but causally unrelated. |
+
+A well-formed analysis typically has **one** root cause and two to
+four contributing causes. Multiple `root` entries indicate the chain
+has not been traced far enough, or that the incident was a genuine
+compound failure — label it explicitly.
+
+## Output
+
+The output has three ordered sections:
+
+1. **Why-chain** — numbered chain, each link with evidence (or
+   `[speculative]` flag) and any branch markers.
+2. **Cause taxonomy** — each identified cause labelled
+   `root` / `contributing` / `amplifying` / `coincidence`, with a
+   one-sentence justification.
+3. **Evidence gaps** — explicit list of claims that could not be
+   verified and what evidence would resolve them. An empty list is
+   fine; omitting the section is not.
+
+May invoke [`systematic-debugging`](../systematic-debugging/SKILL.md) or
+[`bug-analyzer`](../bug-analyzer/SKILL.md) mid-procedure to gather
+evidence for a specific hypothesis, then continue the analysis.
+
+## Do NOT
+
+- Do NOT present a `[speculative]` link as confirmed cause.
+- Do NOT collapse multiple contributing factors into a single root
+  cause to produce a cleaner narrative.
+- Do NOT invent evidence — if a log line is needed but unavailable,
+  name the gap.
+- Do NOT reproduce the systematic-debugging reproduce → isolate → fix
+  loop; this skill assumes the bug is already understood or resolved.
+
+## Gotchas
+
+- Single "root cause" is often an oversimplification — a compound
+  failure with one root and several contributing causes is the norm,
+  not an edge case.
+- An unfalsifiable why-link (e.g. "we don't know") is a stop signal
+  for that branch; do not guess past it.
+- Correlation ≠ causation — require a causal mechanism for every link,
+  not just temporal proximity.
+
+## See also
+
+- [`blameless-post-mortem`](../blameless-post-mortem/SKILL.md) — invokes
+  this skill for the cause section.
+- [`systematic-debugging`](../systematic-debugging/SKILL.md) — live
+  reproduction and fix loop.
+- [`bug-analyzer`](../bug-analyzer/SKILL.md) — static call-site analysis.
+- [`risk-officer`](../risk-officer/SKILL.md) — mitigation framing for
+  corrective actions after the cause is established.

package/dist/agent-src/skills/rule-refactor/SKILL.md

@@ -40,8 +40,8 @@ raises `TOTAL_CAP`.
 ### 1. Inspect the current budget state
 
 ```bash
-python3 scripts/measure_augment_budget.py --json > /tmp/budget-before.json
-python3 scripts/measure_rule_budget.py --json > /tmp/rule-budget-before.json
+./scripts-run src/scripts/measure_augment_budget --json > /tmp/budget-before.json
+./scripts-run src/scripts/measure_rule_budget --json > /tmp/rule-budget-before.json
 ```
 
 ### 2. Run the audit pipeline
@@ -49,9 +49,9 @@ python3 scripts/measure_rule_budget.py --json > /tmp/rule-budget-before.json
 The audit infrastructure already exists — compose it:
 
 ```bash
-python3 scripts/audit_auto_rules.py      # → agents/runtime/reports/auto-rules-audit.{json,md}
-python3 scripts/audit_overlap.py         # → appends overlap pairs to the MD
-python3 scripts/audit_likelihood.py      # → agents/runtime/reports/auto-rules-likelihood.json
+./scripts-run src/scripts/audit_auto_rules      # → agents/runtime/reports/auto-rules-audit.{json,md}
+./scripts-run src/scripts/audit_overlap         # → appends overlap pairs to the MD
+./scripts-run src/scripts/audit_likelihood      # → agents/runtime/reports/auto-rules-likelihood.json
 ```
 
 Then read `agents/runtime/reports/auto-rules-audit.md` end-to-end.
@@ -94,9 +94,9 @@ For each approved verdict:
 
 ```bash
 bash scripts/condense.sh --sync
-python3 scripts/condense.py --generate-tools
-python3 scripts/measure_augment_budget.py --check   # must exit 0
-python3 scripts/skill_linter.py --all               # 0 FAIL
+./scripts-run src/scripts/condense --generate-tools
+./scripts-run src/scripts/measure_augment_budget --check   # must exit 0
+./scripts-run src/scripts/skill_linter --all               # 0 FAIL
 ```
 
 Then run your package's full CI pipeline (see `Taskfile.yml` for the
@@ -107,7 +107,7 @@ canonical sequence) before pushing.
 Append a snapshot to `agents/.augment-budget-history.jsonl`:
 
 ```bash
-python3 scripts/measure_augment_budget.py --trend-append
+./scripts-run src/scripts/measure_augment_budget --trend-append
 ```
 
 Commit the cleanup as a separate chunk from any rule-add commits so

package/dist/agent-src/skills/rule-writing/SKILL.md

@@ -90,8 +90,8 @@ no silent edits, max two rounds.
 ### 3b. Path conventions in frontmatter and body — load-bearing
 
 Three different surfaces, three different rules. Mixing them up will
-either fail the schema (`python3 scripts/validate_frontmatter.py`) or
-fail `python3 scripts/lint_load_context.py`. Canonical reference:
+either fail the schema (`./scripts-run src/scripts/validate_frontmatter`) or
+fail `./scripts-run src/scripts/lint_load_context`. Canonical reference:
 [`templates/rule.md`](../../templates/rule.md) § Path conventions and
 [`docs/contracts/load-context-schema.md`](../../../docs/contracts/load-context-schema.md).
 
@@ -126,10 +126,10 @@ the PR or split by responsibility.
 
 ### 5. Validate
 
-* Run `python3 scripts/skill_linter.py src/rules/{name}.md`
+* Run `./scripts-run src/scripts/skill_linter src/rules/{name}.md`
   → must report **0 FAIL**.
 * Run `bash scripts/condense.sh --sync` to regenerate `dist/agent-src/rules/{name}.md`.
-* Run `python3 scripts/condense.py --generate-tools` to project into `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`.
+* Run `./scripts-run src/scripts/condense --generate-tools` to project into `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`.
 * Run the full CI pipeline locally (see `Taskfile.yml` in this repo for
   the script list) — must exit 0 except for tolerated warnings.
 
@@ -138,7 +138,7 @@ the PR or split by responsibility.
 After validation, before declaring the rule done, run:
 
 ```bash
-python3 scripts/measure_augment_budget.py --check
+./scripts-run src/scripts/measure_augment_budget --check
 ```
 
 If utilisation is `≥ 0.95` (or the check exits non-zero), **STOP** and
@@ -206,7 +206,7 @@ and body links (relative `../../docs/...`, rewriter handles depth).
 1. Complete rule file at `src/rules/{name}.md`
 2. Frontmatter fully populated, no placeholders left
 3. Linter output showing 0 FAIL
-4. Confirmation that `bash scripts/condense.sh --sync` + `python3 scripts/condense.py --generate-tools` ran clean
+4. Confirmation that `bash scripts/condense.sh --sync` + `./scripts-run src/scripts/condense --generate-tools` ran clean
 
 ## Gotchas
 
@@ -214,7 +214,7 @@ and body links (relative `../../docs/...`, rewriter handles depth).
 * Defaulting to `always` "just in case" — token cost is real, `auto` is default.
 * Description like "Rule about X" — it must describe *when*, not *what*.
 * Pasting a workflow into a rule — if it has numbered steps, split into a skill.
-* Forgetting to run `python3 scripts/condense.py --generate-tools` — downstream tools stay stale.
+* Forgetting to run `./scripts-run src/scripts/condense --generate-tools` — downstream tools stay stale.
 * Editing `dist/agent-src/rules/` or `.augment/rules/` directly — those are generated.
 
 ## Frugality Standards

package/dist/agent-src/skills/script-writing/SKILL.md

@@ -138,7 +138,7 @@ Every Taskfile task that wraps a `--quiet`-aware script MUST set
 tasks:
   lint-handoffs:
     silent: true
-    cmd: python3 scripts/lint_handoffs.py {{.QUIET_FLAG}}
+    cmd: ./scripts-run src/scripts/lint_handoffs {{.QUIET_FLAG}}
 ```
 
 The `QUIET_FLAG` var is defined once at the root of `Taskfile.yml`
@@ -156,7 +156,7 @@ do **not** add `silent: true` and do **not** use `{{.QUIET_FLAG}}`.
 
 ### 5. Validate
 
-* Run `python3 scripts/skill_linter.py .agent-src.uncondensed/skills/script-writing/SKILL.md` → 0 FAIL
+* Run `./scripts-run src/scripts/skill_linter src/skills/script-writing/SKILL.md` → 0 FAIL
 * Run `python3 scripts/{your-script}.py --quiet` and the verbose path — exit code 0 on clean, non-zero on failure regardless of flag
 * If the script uses `_lib/script_output`, add a test under `tests/` patterned on `tests/test_script_output.py` — assert `silent` / `minimal` / `verbose` behave per § 2
 * Run the full CI pipeline locally (see `Taskfile.yml` in this repo for the script list) — must exit 0 except for tolerated warnings

package/dist/agent-src/skills/security-audit/SKILL.md

@@ -116,6 +116,7 @@ For each vulnerability:
 - **security** — complementary: security is about writing secure code, this is about finding holes
 - **universal-project-analysis** — provides context about packages and framework usage
 - **bug-analyzer** — some bugs have security implications (chain when found)
+- **untrusted-input-defense** / **lethal-trifecta-guard** (rules) — prompt-injection / agent-config defense; consult when the audited code ingests untrusted content or wires an autonomous egress path
 
 ## Gotcha
 
@@ -130,3 +131,7 @@ For each vulnerability:
 - Do NOT assume frameworks handle everything — verify middleware and config
 - Do NOT confuse code quality issues with security vulnerabilities
 - Do NOT skip dependency checking — known CVEs are real risks
+
+## See also
+
+- [`docs/threat-model.md`](../../docs/threat-model.md) — package attack surface and trust boundary documentation.

package/dist/agent-src/skills/skill-improvement-pipeline/SKILL.md

@@ -64,6 +64,22 @@ Show the user:
 > → {Promote / Reject / Note / Update existing}
 ```
 
+#### Cross-project promotion signal (surfacing only — never an auto-writer)
+
+Same learning now seen in **≥ 2 distinct projects** → strong candidate for a
+*shared* surface (global rule/skill or a `src/patterns/` recipe), not a
+project-local note. **Surface** it; do **not** auto-write:
+
+```
+> Cross-project: also seen in {other-project}.
+> ≥2 projects ⇒ candidate for a shared surface (global rule / skill / pattern).
+> → surface for promotion (human decides; no auto-write)
+```
+
+A *signal*, not a store: no auto-write, no decay, no runtime (the writable
+per-project learning store stays rejected — [[council-agent-memory-sunset]]).
+The human decides whether the cross-project recurrence justifies promotion.
+
 ### Step 3: Classify
 
 #### Category tag
@@ -96,10 +112,10 @@ Decide what to create:
 - **Update existing** → use `skill-management` skill
 
 After creation:
-1. Run `python3 scripts/skill_linter.py {path}` — must pass (0 fail)
+1. Run `./scripts-run src/scripts/skill_linter {path}` — must pass (0 fail)
 2. Copy to `.augment/`
-3. Mark hash: `python3 scripts/condense.py --mark-done "{relative_path}"`
-4. Regenerate tools: `python3 scripts/condense.py --generate-tools`
+3. Mark hash: `./scripts-run src/scripts/condense --mark-done "{relative_path}"`
+4. Regenerate tools: `./scripts-run src/scripts/condense --generate-tools`
 
 ### Step 5: Decide scope
 

package/dist/agent-src/skills/skill-management/SKILL.md

@@ -42,7 +42,7 @@ Do not use when:
 7. Validate — condensed version must be: easier to scan, easier to trigger, at least as safe
 
 **Iron rule:** Condensation must NOT weaken validation or remove decision hints that prevent mistakes.
-**Linter gate:** After condensation, run `python3 scripts/skill_linter.py` on the file — must be 0 FAIL.
+**Linter gate:** After condensation, run `./scripts-run src/scripts/skill_linter` on the file — must be 0 FAIL.
 
 ### Mode: Decondense
 **Trigger:** "expand skill", "decondense skill", "make skill clearer"
@@ -56,7 +56,7 @@ Do not use when:
 7. Validate — expanded version must be: clearer, still executable, not noisy
 
 **Iron rule:** Expansion must NOT turn skills into documentation. Add context, not prose.
-**Linter gate:** After expansion, run `python3 scripts/skill_linter.py` on the file — must be 0 FAIL.
+**Linter gate:** After expansion, run `./scripts-run src/scripts/skill_linter` on the file — must be 0 FAIL.
 
 ### Mode: Refactor
 **Trigger:** "refactor skill", "improve skill", "fix skill structure"
@@ -68,7 +68,7 @@ Do not use when:
 5. Refine scope — ensure single responsibility, split if multiple workflows
 6. Compare before/after — must be clearer, at least as executable, not broader
 
-**Linter gate:** After refactoring, run `python3 scripts/skill_linter.py` on the file — must be 0 FAIL.
+**Linter gate:** After refactoring, run `./scripts-run src/scripts/skill_linter` on the file — must be 0 FAIL.
 
 **Independence check:** After refactoring, verify the skill is still executable without opening any guideline.
 If the refactor introduced guideline delegations ("see guideline X"), ensure the Procedure still works standalone.

package/dist/agent-src/skills/skill-reviewer/SKILL.md

@@ -154,7 +154,7 @@ Before scoring the 5 Killers, verify structure:
 - Gotchas
 - Do NOT
 
-**Linter:** Run `python3 scripts/skill_linter.py` on any skill after review — must be 0 FAIL.
+**Linter:** Run `./scripts-run src/scripts/skill_linter` on any skill after review — must be 0 FAIL.
 
 **Rules** — must be:
 - Short and directive

package/dist/agent-src/skills/skill-writing/SKILL.md

@@ -159,7 +159,7 @@ description: "Use when writing Playwright E2E tests — locators, assertions,
 ```
 
 The *good* version routes correctly on *"my E2E keeps flaking on CI"*
-without naming Playwright. Run `python3 scripts/audit_skill_descriptions.py`
+without naming Playwright. Run `./scripts-run src/scripts/audit_skill_descriptions`
 after writing; if flagged `too-short` or `no-trigger-prefix`, rewrite
 before commit.
 
@@ -320,7 +320,7 @@ each criterion to one falsifiable sentence.
 
 **Loop** (orchestrated by `scripts/run_skill_evals.py`):
 
-1. **Scaffold** — `python3 scripts/run_skill_evals.py scaffold {skill}`
+1. **Scaffold** — `./scripts-run src/scripts/run_skill_evals scaffold {skill}`
    creates `runs/{timestamp}-{baseline,with-skill}/` and seeds each
    scenario's `meta.json`.
 2. **Baseline run** — spawn one sub-agent per scenario **without** the
@@ -331,10 +331,10 @@ each criterion to one falsifiable sentence.
 4. **Grade** — for each scenario, write a `grade.json` file with
    per-assertion pass/fail. Deterministic assertions auto-grade;
    rubric assertions need a grader sub-agent.
-5. **Aggregate** — `python3 scripts/run_skill_evals.py aggregate {skill}
+5. **Aggregate** — `./scripts-run src/scripts/run_skill_evals aggregate {skill}
    --run {timestamp}` produces `runs/{timestamp}-benchmark.json` with
    pass-rate, timing, token deltas baseline-vs-with-skill.
-6. **Report** — `python3 scripts/run_skill_evals.py report {skill}
+6. **Report** — `./scripts-run src/scripts/run_skill_evals report {skill}
    --run {timestamp}` prints the diff. Iterate on the skill body
    until `with-skill` outperforms `baseline` on every scenario.
 
@@ -403,7 +403,7 @@ utility libs, or simple state managers.
 * Including baseline knowledge the model already has
 * Description too long or not a trigger
 * Renaming a heading to "Procedure:" without numbered steps or `###` sub-headings
-* **Always run `python3 scripts/skill_linter.py` before saving — 0 FAIL required**
+* **Always run `./scripts-run src/scripts/skill_linter` before saving — 0 FAIL required**
 
 ## Frugality Standards
 

package/dist/agent-src/skills/skill-writing/evals/triggers.json

@@ -1,5 +1,6 @@
 {
   "skill": "skill-writing",
+  "last_eval": "2026-06-16",
   "description": "5 should-trigger + 5 should-not-trigger queries. No query mentions 'skill-writing' directly. Near-misses share 'skill' vocabulary but route to skill-management, lint-skills, or unrelated skills.",
   "queries": [
     {"q": "let's create a skill for database migrations", "trigger": true},

package/dist/agent-src/skills/source-discovery/SKILL.md

@@ -0,0 +1,182 @@
+---
+model_tier: medium
+name: source-discovery
+description: "Use BEFORE planning/coding against a DB schema, API/GraphQL shape, DTO/Model/Entity, or vendor package — read the real source, emit an Evidence Report, stop inventing fields."
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# source-discovery
+
+The procedure behind the [`source-discovery`](../../rules/source-discovery-gate.md)
+rule. Hand-off target from [`think-before-action`](../../rules/think-before-action.md)
+when a task touches **external or expensive** structure. Definitions
+(Evidence Report buckets, provenance, trust tiers, the DB-not-in-codebase
+boundary, the card-worthiness threshold) live in
+[`evidence-discipline`](../../agent-src/contexts/execution/evidence-discipline.md) —
+read it once; this file is the executable procedure.
+
+## When to use
+
+Before you plan or code against a structure you have **not** confirmed this
+session: a DB schema, an API/GraphQL shape, a DTO/Model/Entity, a vendor
+package's surface, or any field/endpoint/column/value.
+
+Do NOT use for: trivial edits (rename/typo/format), structure already verified
+this session, or when the user supplied the verified structure (gate-skip per
+`rdp-gate`).
+
+## The shape of a run
+
+```
+discover the real source  →  Evidence Report (Verified / Assumed / Gaps)  →  plan  →  act  →  verify with the real tool
+```
+
+Scaffold the report cheaply so it never gets skipped:
+
+```bash
+python3 src/scripts/evidence_report.py git-state            # fail-fast: abort if a rebase/merge/cherry-pick is in progress
+python3 src/scripts/evidence_report.py init --task "<task>" # writes the gitignored session report
+python3 src/scripts/evidence_report.py add --bucket verified --claim "users.email is unique" --source "db/schema/users.sql:23"
+```
+
+**Provenance on every item** (`observed_at` / `source` / `version`). Within a
+session a read is fresh until the file's mtime changes; **invalidate all session
+reads when `git rev-parse HEAD` changes**; across sessions always re-read.
+
+## Step 0 — Resolve local structure fresh (NO persistent index)
+
+Resolve name → path **fresh** each lookup with `rg` / glob, then read the file
+fresh. There is **no** persistent bootstrap index (a measured `rg`-latency
+problem on a large monorepo is the only thing that would justify one — deferred).
+
+```bash
+rg -n "class User\b|model User|CREATE TABLE .*users" --type-add 'src:*.{php,ts,js,py,go,rb,sql}' -t src
+```
+
+## Procedure — discover and analyze each surface before planning
+
+1. **Identify** which surface(s) the task touches (DB / API / vendor / DTO).
+2. **Discover** the real source via the matching sub-procedure below — local
+   before remote, analyzing the actual definition, never memory.
+3. **Record** each fact into the Evidence Report with provenance, then build the
+   plan from the report.
+
+### A. DB schema — in-codebase = LOCAL, read fresh, no card
+
+**In-codebase** (schema defined by repo migrations / models / ORM / app code,
+**including** schemaless stores the app controls — Mongoose / Prisma / Firestore
+rules) → always local & fresh. Dump tables, columns, types, primary/foreign/
+unique keys, indexes, relations, and derived filter/sort/group-ability into the
+session cache with provenance — framework-neutral (MySQL / Postgres / SQLite;
+ORM-agnostic). The **migration is intended truth, the live DB is actual**;
+divergence is a drift signal worth surfacing. Only **negative facts** graduate to
+a committed card (see [`database`](../database/SKILL.md) for the dump procedure).
+
+### B. API / GraphQL — probe + confirm
+
+Resolve an OpenAPI/Swagger spec or GraphQL introspection from config/task first.
+Else run a **read-only, idempotent `GET` probe**, reduced with `jq` — never a full
+dump, never a write/stateful call, never prod without permission, secrets-aware
+per [`security-sensitive-stop`](../../rules/security-sensitive-stop.md). A probed
+positive shape is `trust: low` ("Assumed (from card)" if card-sourced) and must
+be confirmed against the live surface before use.
+
+### C. Vendor / external-DB docs — card-worthy
+
+Card-worthy = **(external package / remote API / DB-not-in-codebase)** AND **(≥3
+distinct methods/fields *intended* to be used, OR the source exposes >50 methods
+and ≥1 is used, OR a prior hallucination on it, OR local types/README are
+insufficient)** — judged on *intended* use at discovery (still built **before**
+coding). For a card-worthy dependency named in the task: **local-first**
+(`node_modules` / `vendor` README + type defs; the **installed version is ground
+truth**), then the net (registry → repo host → homepage). **Pin the remote ref to
+the installed version — never blind `main`.** Reuse
+[`external-reference-deep-dive`](../../rules/external-reference-deep-dive.md) +
+[`markitdown`](../markitdown/SKILL.md); honor `source-confidentiality`,
+`untrusted-input-defense`, `lethal-trifecta-guard`. Persist via the
+`knowledge-card` template under `agents/knowledge/<source>.md`.
+
+### D. DTO / Model / Entity — local, read fresh
+
+Resolve and read the actual class fresh (Step 0). In-codebase → local, no card.
+
+### E. Global cards — leads only (v2, ADR-100)
+
+When `knowledge.global_sharing.enabled` (user-global, **default off until cross-project reuse measured** — ADR-103), a matching
+card may exist in the per-user file-first store
+(`~/.event4u/agent-config/knowledge/`), promoted from another project. **Lead,
+never a build input**:
+
+- Load **negative facts + pointers** as leads (`trust: durable`).
+- Load **positive structure** under **"Assumed (from card · GLOBAL,
+  unverified)"** — record via `evidence_report.py add --bucket assumed --origin
+  global …` and **re-confirm vs the live source this session** before use
+  (version skew / schema drift). Never "Verified" on the global card alone.
+- `public`/`vendor` seen in ≥ `auto_promote_threshold` distinct repos → one-tap
+  promotion **suggestion** (never silent); `proprietary` is manual-only. Record
+  sightings via `_lib/knowledge_global_promote.py record-seen`.
+
+## Missing structure → fixed extension workflow
+
+When the field/endpoint/table you need is **not** there:
+
+1. **Search** the relevant sources.
+2. **Not found** — record the **absence-search log** with `searched` *and*
+   `not_searched` (via `evidence_report.py add --bucket gaps --searched … --not-searched …`).
+3. **Negative-fact card** — only **after the search is exhausted across all
+   relevant sources** for that claim: write `type: anti-hallucination`,
+   `polarity: negative`, with `actionable` + `next_step` + a `revalidate_if`
+   trigger ("an OpenAPI spec / contracts dir is added"). A negative fact is a
+   **current-state fact** ("searched X, didn't find X") — not a card-worthiness
+   *decision* (that belongs in notes/ADR).
+4. **Extension plan** — a codebase-fitting plan (migration + model/cast/factory/
+   seeder, or the stack equivalent). **Plan only, never silent execution**
+   ([`scope-control`](../../rules/scope-control.md)).
+
+## Verify after acting (Phase-3 wiring)
+
+After acting on discovered structure, verify with the **real tool** per the
+[`think-before-action`](../../rules/think-before-action.md) matrix — `curl` /
+Playwright / debugger / test runner / DB query. Any **Assumed (from card)** or
+`trust: low` line used without this-session confirmation is a violation surfaced
+post-task. A stale card (installed-version mismatch OR `last_verified` older than
+N days) is **lead-only**: negative facts + pointers stay usable, positive
+structure must be re-confirmed. Green is not a correctness proof — high-risk /
+irreversible steps verify regardless.
+
+## Output
+
+The Evidence Report (gitignored session cache), three buckets, soft-capped to
+~10–20 decision-relevant facts, produced **before** the plan; plus, where the
+threshold is met, a thin committed card.
+
+## Evidence v2 — self-building context (heuristics only, never a bypass)
+
+Curated project-intelligence (Class A config digests, Class B observed conventions,
+Class C learned lessons) may be loaded to inform *where to look* and *what convention
+to expect* — but read **for heuristics only** and **never** bypasses a fresh structural
+read. A field/endpoint/column/value is still confirmed against a live source this
+session. v2 capture is **write-only into gitignored intake** (agent may *suggest* a
+signal, never silently commit); trust and commit are always human-gated. Full model +
+the three classes + memory tiers:
+[`project-intelligence`](../../agent-src/contexts/execution/project-intelligence.md).
+
+## Gotchas
+
+- A card's positive structure is **never** "Verified" on the card alone — it is
+  "Assumed (from card)" until confirmed this session (R4 P1).
+- L0–L4 depth labels are documentation only — the same evidence rules apply at
+  every tier; no per-tier relaxation.
+- The self-log is instrumentation; the deterministic teeth are pointer-CI + the
+  eval. Do not treat a written "verified" as proof.
+
+## Do NOT
+
+- Do NOT plan or code against an unconfirmed field/endpoint/column.
+- Do NOT treat a card as a source of truth or a build input.
+- Do NOT execute a schema/API extension silently — plan, then hand back.
+- Do NOT read an intermediate tree mid git-op — fail-fast.