@event4u/agent-config 9.9.0 → 9.10.0

package/dist/agent-src/contexts/execution/evidence-discipline.md

@@ -1,9 +1,10 @@
 # Evidence Discipline — Report format, provenance, enforcement reality
 
-Canonical definitional spine for evidence-first structure discipline. Loaded by
-[`source-discovery`](../../rules/source-discovery-gate.md) rule and skill. Skill
-holds the *procedure*; this file holds the *definitions* every later phase, the
-linter, and ADRs refer back to.
+Canonical definitional spine for the evidence-first structure discipline. Loaded
+by the [`source-discovery`](../../rules/source-discovery-gate.md) rule and the
+[`source-discovery`](../../skills/source-discovery/SKILL.md) skill. The skill
+holds the *procedure* (how to discover each surface); this file holds the
+*definitions* every later phase, the linter, and the ADR refer back to.
 
 ## The invariant
 
@@ -13,78 +14,86 @@ EVERY FIELD, ENDPOINT, COLUMN, AND VALUE TRACES TO file:line · SDL · migration
 LOCAL BEFORE REMOTE. REAL SOURCE BEFORE GUESSING.
 ```
 
-Product is a **discipline**, not a knowledge database. A card is only an optional
-cache for *expensive* evidence — never a source of truth, never a build input.
+The product is a **discipline**, not a knowledge database. A card is only an
+optional cache for *expensive* evidence — never a source of truth, never a
+build input.
 
-## Evidence Report — discovery output
+## Evidence Report — the discovery output
 
-Gitignored session scratchpad (`agents/memory/knowledge/session/`, overwritten each
-task), produced **before** the plan, soft-capped to ~10–20 decision-relevant facts.
-Three buckets:
+A gitignored session scratchpad (`agents/memory/knowledge/session/`, overwritten
+each task), produced **before** the plan, soft-capped to ~10–20 decision-relevant
+facts (a smell-test, not a hard gate). Three buckets:
 
 - **Verified** — confirmed **this session** against a real source, **or** durable
-  committed-card content (negative facts + pointers, pointer-CI green). Nothing else qualifies.
-- **Assumed (from card)** — positive structural claims from a committed card but
-  **not** confirmed this session; explicitly a hypothesis. A card's positive structure
-  is **never** "Verified", even with a green pointer (R4 P1).
+  committed-card content (negative facts + pointers, pointer-CI green). Nothing
+  else qualifies.
+- **Assumed (from card)** — positive structural claims taken from a committed
+  card but **not** confirmed this session; explicitly a hypothesis. A card's
+  positive structure is **never** "Verified", even with a green pointer (R4 P1).
 - **Gaps** — missing evidence the decision needs (negative facts in the making).
 
-Feeds the plan. Not a forensic log, not hard enforcement. Produce cheaply via
-`evidence_report.ts` so it never gets skipped.
+It feeds the plan. It is **not** a forensic log and is **not** hard enforcement.
+Produce it cheaply via `evidence_report.ts` (template automation) so it never
+gets skipped.
 
 ## Provenance and freshness
 
-- Every item carries `observed_at`, `source`, `version` where one exists. Card
-  **positive-structure lines** carry **per-line** `observed_at` / `source_version` (R4 P5).
-- **Within a session:** read is fresh until file's **mtime** changes.
-- **Invalidate all session reads when `git rev-parse HEAD` changes** — new HEAD means
-  tree may have moved.
-- **Fail-fast mid git-op:** if rebase/merge/cherry-pick is in progress
-  (`.git/MERGE_HEAD`, `.git/CHERRY_PICK_HEAD`, or `.git/rebase-merge`/`rebase-apply`
-  present), do **not** read an intermediate tree — stop and surface it (R4 P6,
-  hole-3). *(`.git/REBASE_HEAD` excluded — lingers as stale ref after completed
-  rebase, not a live-op marker.)* `evidence_report.ts git-state` is the
-  deterministic check.
+- Every evidence item carries `observed_at`, `source`, and `version` where one
+  exists. Card **positive-structure lines** carry **per-line** `observed_at` /
+  `source_version` (R4 P5).
+- **Within a session:** a read is fresh until the file's **mtime** changes.
+- **Invalidate all session reads when `git rev-parse HEAD` changes** — a new HEAD
+  means the tree may have moved under you.
+- **Fail-fast mid git-op:** if a rebase/merge/cherry-pick is in progress
+  (`.git/MERGE_HEAD`, `.git/CHERRY_PICK_HEAD`, or a `.git/rebase-merge`/
+  `rebase-apply` directory present), do **not** read an intermediate tree — stop
+  and surface it (R4 P6, hole-3). *(`.git/REBASE_HEAD` is excluded — it lingers as
+  a stale ref after a completed rebase and is not a live-op marker.)* The
+  `evidence_report.ts git-state` subcommand is the deterministic check.
 - **Across sessions:** always re-read. No file hashing, no content-hash theater.
 
 ## Two-file split
 
 | File | Home | Tracked? | Holds |
 |---|---|---|---|
-| **Ephemeral session cache** | `agents/memory/knowledge/session/` | gitignored | Evidence Report + raw probe/introspection dumps + absence-search log |
+| **Ephemeral session cache** | `agents/memory/knowledge/session/` | gitignored | Evidence Report + raw probe/introspection dumps + the absence-search log |
 | **Committed card** | `agents/knowledge/<source>.md` | tracked | thin distillation: `trust: durable` negative facts + pointers; positive structure as per-line last-verified hypothesis |
 
-Committed card extends `context-document` mechanism (a specialized context type)
-— **not** a second knowledge system.
+The committed card extends the `context-document` mechanism (a specialized
+context type) — it is **not** a second knowledge system.
 
 ## DB-not-in-codebase boundary (R4 P2)
 
-- **In-codebase** = schema defined by repo migrations / models / ORM / app code —
-  **including** schemaless stores the app controls (Mongoose, Prisma, Firestore
-  rules). → always **local, read fresh, no card**.
+- **In-codebase** = the schema is defined by repo migrations / models / ORM /
+  app code — **including** schemaless stores whose shape the app controls
+  (Mongoose, Prisma, Firestore rules). → always **local, read fresh, no card**.
 - **DB-not-in-codebase** = no repo migrations/models/app-code define the schema
-  **and** app does not control it (vendor SaaS, partner, legacy DB). → may be
+  **and** the app does not control it (vendor SaaS, partner, legacy DB). → may be
   **card-worthy** (remote evidence).
 
 ## Negative facts (R4 P4)
 
 A negative fact is a **current-state fact** — "searched X, did not find Y" — not a
-card-worthiness *decision* (belongs in notes/ADR, never an anti-hallucination card).
-Write a negative-fact card **only after search is exhausted across all relevant
-sources**, logging `searched` *and* `not_searched`, attach a `revalidate_if` trigger.
+card-worthiness *decision* (that belongs in notes/ADR, never an anti-hallucination
+card). Write a negative-fact card **only after the search is exhausted across all
+relevant sources** for that claim, logging `searched` *and* `not_searched`, and
+attach a `revalidate_if` trigger (e.g. "an OpenAPI spec / contracts dir is added").
 
 ## Card-worthiness threshold (R3 F-3, R4 P2/P7)
 
 Card-worthy = **(external package / remote API / DB-not-in-codebase)** AND **(≥3
-distinct methods/fields *intended* to be used OR source exposes >50 methods and ≥1
-is used OR prior hallucination OR local types/README insufficient)**. Judged on
-**intended** use at discovery. Cross-feature duplication check flags structure
-discovered in >1 session without a card as "should-have-been-card-worthy".
+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 — a card may be upgraded
+later if usage grows, so it is still built *before* coding. A cross-feature
+duplication check flags structure discovered in >1 session without a card as
+"should-have-been-card-worthy".
 
 ## L0–L4 — descriptive, not prescriptive
 
-L0–L4 are human shorthand for discovery depth; documentation only. **Same** evidence
-rules apply at every tier — no enforced state machine, no per-tier relaxation.
+L0–L4 are human shorthand for how deep a discovery went; they are documentation
+only. The **same** evidence rules apply at every tier — no enforced state
+machine, no per-tier evidence relaxation.
 
 ## Honest enforcement reality
 
@@ -94,55 +103,61 @@ A MODEL THAT INVENTS A FIELD CAN ALSO WRITE A FALSE "VERIFIED".
 THE TEETH ARE POINTER-CI (DETERMINISTIC) + THE ANTI-HALLUCINATION EVAL (EMPIRICAL).
 ```
 
-- **Instrumentation (soft):** Evidence Report and any `card_claims` self-log. Useful
-  signal; never oversold as a guarantee.
+- **Instrumentation (soft):** the Evidence Report and any `card_claims` self-log.
+  Useful signal; never oversold as a guarantee.
 - **Teeth (hard):** pointer-resolution CI (path exists / URL 200, strict-mode
-  content-compare) + multi-evidence git-ancestry consistency check +
-  per-surface anti-hallucination eval with variance baseline.
+  content-compare) + the multi-evidence git-ancestry consistency check +
+  the per-surface anti-hallucination eval with a variance baseline.
 
 ## Global layer (v2 — cross-project card sharing, ADR-100)
 
-An *expensive* (remote) card may be promoted from project-local `agents/knowledge/`
-to per-user **file-first** global store at `~/.event4u/agent-config/knowledge/`
-(no daemon / DB / vector index / decay — 2026-06-14 Layer-2 sunset's core preserved).
-**Storage, not governed** like a committed card: unversioned, a cache, never a source
-of truth. Gated by `knowledge.global_sharing` setting (**default OFF until
-cross-project reuse is measured across ≥ 2 real projects** — ADR-103 amends ADR-100
-Phase 0; `enabled: false` fully no-ops the layer — v1 unaffected; operator opts in
-explicitly; default flips back only on positive reuse signal).
-
-- **Global card is a distillation, not a copy.** `trust: durable` core is
-  **negative facts + pointers**; positive structure is explicit per-line
-  **hypothesis** — never copied as build input.
-- **Leads-only consumption.** Global card enters Evidence Report as **"Assumed (from
-  card · GLOBAL, unverified)"** — positive structure must be re-confirmed against
-  live source *this session*. Negative facts + pointers are usable as leads.
-  Global-sourced positive structure is **never** "Verified".
-- **Origin-tier scoping is the privacy floor.** `public` auto-shareable; `vendor`
-  shareable **post-redaction**; `proprietary` **manual-only, default-off regardless
-  of `enabled`** — no client-A schema leaks into client-B.
-- **Redaction on write.** Promotion runs the `low-impact-corpus-privacy-floor` +
-  `source-confidentiality` pattern set and **halts** on any hit — never
+An *expensive* (remote) card may be promoted from project-local
+`agents/knowledge/` to a per-user **file-first** global store at
+`~/.event4u/agent-config/knowledge/` (no daemon / DB / vector index / decay —
+the 2026-06-14 Layer-2 sunset's core is preserved). It is **storage, not
+governed** like a committed card: unversioned, a cache, never a source of
+truth — the per-card provenance footer is its audit trail. Gated by the
+user-global `knowledge.global_sharing` setting (**default OFF until cross-project
+reuse is measured across ≥ 2 real projects** — ADR-103 amends ADR-100 Phase 0;
+`enabled: false` fully no-ops the layer — v1 unaffected; an operator opts in
+explicitly and the default flips back only on a positive reuse signal).
+
+- **A global card is a distillation, not a copy.** Its `trust: durable` core is
+  **negative facts + pointers**; positive structure is an explicit per-line
+  **hypothesis** — the same shape as a committed card, never positive structure
+  copied as a build input.
+- **Leads-only consumption.** A global card loaded in a consuming project enters
+  the Evidence Report under **"Assumed (from card · GLOBAL, unverified)"** — its
+  positive structure must be re-confirmed against the live source *this session*
+  before use (version skew, schema drift). Negative facts + pointers are usable
+  as leads. Global-sourced positive structure is **never** "Verified".
+- **Origin-tier scoping is the privacy floor.** `public` (registry / GitHub /
+  docs) auto-shareable; `vendor` (Stripe / AWS / …) shareable **post-redaction**;
+  `proprietary` (in-house DB / private API / client schemas) **manual-only,
+  default-off regardless of `enabled`** — no client-A schema leaks into client-B.
+- **Redaction on write.** Promotion runs the `low-impact-corpus-privacy-floor`
+  + `source-confidentiality` pattern set and **halts** on any hit — never
   silent-shares, never auto-rewrites.
-- **Promotion is hybrid.** Card seen in ≥`auto_promote_threshold` distinct repos
-  triggers a one-tap **suggestion**; never a silent write.
+- **Promotion is hybrid.** A `public`/`vendor` card seen in ≥`auto_promote_threshold`
+  distinct repos triggers a one-tap **suggestion**; never a silent write.
 
 ## Evidence v2 rollback target (Phase 0)
 
 Evidence v2 (self-building project context — Class A config-pointers, Class B
-observed conventions, Class C learned lessons) is an **additive** layer. Rollback
-target is fixed and measurable:
+observed conventions, Class C learned lessons) is an **additive** layer. Its
+rollback target is fixed and measurable:
 
 ```
 v2 ROLLBACK = DISABLE ALL CURATED ACCUMULATED CONTEXT EXCEPT CLASS-A CONFIG-POINTERS.
 THE MEASURABLE BASELINE TO REVERT TO IS v1 DISCIPLINE WITH NO ACCUMULATED CONTEXT.
 ```
 
-Class A (config-derived pointers) is deterministic, drift-proof, no accumulation
-risk → survives rollback. Class B/C are accumulation layers; if v2 eval shows
-accumulated context raises error rate or cost is disproportionate, those layers are
-disabled and agent runs v1 alone — acceptable outcome. "Self-improving" is a
-hypothesis, not a law; rollback target makes the hypothesis falsifiable.
+Class A (config-derived pointers) is deterministic, drift-proof, and carries no
+accumulation risk, so it survives a rollback. Class B/C are the accumulation
+layers; if a v2 eval shows accumulated context raises the error rate or its cost
+is disproportionate, those layers are disabled and the agent runs on v1 discipline
+alone — an acceptable outcome (v1's value stood on its own). "Self-improving" is a
+hypothesis, not a law; the rollback target is what makes the hypothesis falsifiable.
 
 ## See also
 

package/dist/agent-src/contexts/execution/orchestration-benchmark-gate.md

@@ -1,19 +1,20 @@
 # Orchestration Benchmark & Demotion Gate (Phase 6 → telemetry-demotion)
 
 Originally the falsification gate the auto-orchestration roadmap was built
-around: shipped default for `subagents.auto` would flip toward `on` only on a
-benchmark proving a net win at held quality.
+around: the shipped default for `subagents.auto` would flip toward `on` only
+when a real benchmark proved a net win at held quality.
 
 **As of 2026-07-09 the shipped default IS `on`** on subagent-capable hosts
 (ADR-117; [`orchestration-default-flip-verdict`](../../../../agents/settings/contexts/orchestration-default-flip-verdict.md)
-§ 2026-07-09). Flipped on a **bounded-downside re-evaluation**, not a passed
-benchmark: rigorous paired bench:ab not producible here (no runtime executing
-model `Task`/`Agent` calls), win-validation deadlocked (telemetry needs `on`,
-`on` gated on telemetry). Re-eval broke the deadlock — downside of `on` is
-structurally small (delegable slices cost-routed to cheapest tier,
-classification fires only on real structural signals, every return verified) →
-`on` gathers realized telemetry responsibly. This gate now governs
-**demotion**: measured regression flips default back to `ask`.
+§ 2026-07-09). It was flipped on a **bounded-downside re-evaluation**, not a
+passed benchmark: a rigorous paired bench:ab is not producible in this harness
+(no runtime that executes model `Task`/`Agent` calls), and the win-validation
+was deadlocked (telemetry needs `on`, `on` was gated on telemetry). The
+re-evaluation broke the deadlock by showing the downside of `on` is
+structurally small — delegable slices are cost-routed to the cheapest capable
+tier, classification fires only on real structural signals, every return is
+verified — so `on` gathers the realized telemetry responsibly. This gate now
+governs **demotion**: a measured regression flips the default back to `ask`.
 
 ## Measurement — pin the method
 
@@ -42,18 +43,18 @@ HONEST-NULL EXIT: no win, or quality regressed → KEEP the conservative default
 
 ## Default state + demotion — host-gated
 
-Shipped default for `subagents.auto` is `on` on hosts whose manifest reports
-`subagent_spawn: true` (`off` elsewhere) — set directly in
+The shipped default for `subagents.auto` is `on` on hosts whose capability
+manifest reports `subagent_spawn: true` (`off` elsewhere) — set directly in
 `src/config/agent-settings.template.yml`. `resolveShippedDefault()` remains the
-host-gated resolver, now serving **demotion**: fed a `fail` verdict from
-accumulated real-world orchestration telemetry, resolves back to `ask`
-(conservative). A `pass` keeps `on`. Demotion path is a one-line edit,
-host-gated by the manifest at runtime.
+host-gated resolver and now serves **demotion**: fed a `fail` verdict from
+accumulated real-world orchestration telemetry, it resolves back to `ask`
+(conservative). A `pass` verdict keeps `on`. The demotion path is a one-line
+edit, host-gated by the manifest at runtime.
 
-The 2026-07-09 flip reconciles the user's "default on" goal with the council's
-"prove-first": rather than wait on a benchmark that cannot be produced here,
-`on` ships because its downside is bounded and reversible, and realized
-telemetry is now free to accrue and drive demotion if it regresses.
+The 2026-07-09 flip is the reconciliation of the user's "default on" goal with
+the council's "prove-first": rather than wait on a benchmark that cannot be
+produced here, `on` ships because its downside is bounded and reversible, and
+realized telemetry is now free to accrue and drive demotion if it regresses.
 
 ## Reproducibility
 
@@ -69,7 +70,7 @@ is auditable rather than asserted.
 
 ## Related
 
-- ADR-118 (`docs/decisions/ADR-118-loop-engineering-boundaries.md`) — demotion stays manual human edit by decision; never automated (disposition #1).
+- ADR-118 (`docs/decisions/ADR-118-loop-engineering-boundaries.md`) — demotion stays a manual human edit by decision; never automated (disposition #1).
 - [`auto-orchestration-activation`](auto-orchestration-activation.md) — the `subagents.auto` key this gate sets the default for.
 - [`host-capability-manifest`](host-capability-manifest.md) — `subagent_spawn` gates the flip.
 - [`orchestration-telemetry`](orchestration-telemetry.md) — the per-dispatch metrics the benchmark aggregates.

package/dist/agent-src/contexts/execution/orchestration-telemetry.md

@@ -185,6 +185,30 @@ derivable from this data. A percentage would require an additive
 absolute-baseline field on this object (deferred follow-up). Reader:
 [`src/scripts/_lib/orchestration_savings.ts`](../../../../src/scripts/_lib/orchestration_savings.ts).
 
+## Payload-hash drift report (`payload_hash` × `cache_hit`)
+
+Join the two fields into a stable/unstable prefix-stability cohort split:
+
+```bash
+./scripts-run src/scripts/orchestration_payload_hash_drift [--dir <path>] [--format text|json]
+```
+
+Reader: [`src/scripts/_lib/payload_hash_drift.ts`](../../../../src/scripts/_lib/payload_hash_drift.ts).
+Zero recorded lines carrying both fields is the current expected state — both
+are lean-init extensions with no caller wiring a real value into them yet;
+the report says so rather than presenting empty input as a pass.
+
+**Refusal (report, never act).** `cache_hit` is a provider-reported proxy for
+HOST-controlled cache behaviour — this package causes the dispatch but does
+not control whether the host reports a hit. Per
+[`ADR-118`](../../../../docs/decisions/ADR-118-loop-engineering-boundaries.md)
+§1 (a measure→adjust loop is automated only when it is a *direct* measure of
+the failure mode, the false-positive rate is low, and human judgement adds no
+unique information), a host-controlled proxy fails the direct-measure
+condition outright. No consumer of `payload_hash` or `cache_hit` may wire a
+measure→adjust step off them — no default flip, no tier change, no dispatch
+throttle. They are read-only diagnostic fields.
+
 ## Related
 
 - [`audit-log-v1`](../../../../docs/contracts/audit-log-v1.md) — the frozen