@event4u/agent-config 8.7.0 → 8.8.0

package/docs/succession.md

@@ -0,0 +1,80 @@
+# Succession — the minimal knowledge to take over
+
+> **Bus-factor doc (road-to-maintainer-bus-factor Phase 3).** If the maintainer
+> is unavailable, this is what a successor needs to keep `main` healthy and cut
+> releases. **No secret values live here — pointers only.** Companion:
+> [`release-runbook.md`](release-runbook.md) (the how-to-release steps).
+
+## Honest bus-factor (tracked, not inflated)
+
+- **Distinct humans who have reviewed/merged in the trailing 90 days: 1** (the
+  maintainer, `@matze4u`). The project is a single-maintainer repo; an AI
+  self-review gate (deferred — see the roadmap Phase 1) raises the floor but is
+  **not** independent human review.
+- Recompute this number honestly at any time:
+
+  ```bash
+  # merged PRs in the last 90 days + who reviewed them
+  gh pr list --state merged --search "merged:>=$(date -v-90d +%Y-%m-%d 2>/dev/null || date -d '90 days ago' +%Y-%m-%d)" \
+    --json number,author,reviews \
+    --jq '[.[] | .reviews[]?.author.login] | unique'
+  ```
+
+  Report the count as-is. A bus-factor of 1 stated plainly beats a bus-factor of
+  1 implied to be more.
+
+## Secrets / tokens — where they live, what they gate
+
+Configured in **GitHub → Settings → Secrets and variables → Actions** (repo
+secrets), never in the tree. None is required for the *core* release (version
+bump + tag + GitHub Release); they gate the **downstream** publish/deploy legs.
+
+| Secret | Gates | Missing → |
+|---|---|---|
+| `RELEASE_PR_TOKEN` (optional PAT / App token, `contents:write` + `pull-requests:write`) | Unattended release PR checks in [`release.yml`](../.github/workflows/release.yml) | One manual **"Approve workflows to run"** click per release (deliberate checkpoint, not a failure). |
+| — (none: **npm OIDC Trusted Publishing**) | `publish-npm.yml` — uses `id-token: write`, no stored npm token | If OIDC trust is misconfigured on npmjs, npm publish fails; fix the trusted-publisher config on the npm package, not a secret. |
+| `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_WORKER_SUBDOMAIN`, `MCP_SMOKE_TOKEN` | `deploy-mcp-worker.yml` (MCP worker deploy + smoke) | MCP worker deploy skips/fails; core release unaffected. |
+| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` | `cross-model-canary.yml` + any AI-council / self-review automation | Canary + council automation skip; core release unaffected. |
+| `GITHUB_TOKEN` (auto-provided) | all workflows' default auth | n/a — GitHub injects it. |
+
+The live source of truth for which workflow needs which secret is the
+`secrets.*` references in [`.github/workflows/`](../.github/workflows/) — grep
+there if this table drifts:
+
+```bash
+grep -rhoE "secrets\.[A-Z_]+" .github/workflows/ | sort -u
+```
+
+## Operator-gated steps (need a human with credentials)
+
+- **Release-PR workflow approval** — the "Approve workflows to run" click when
+  `RELEASE_PR_TOKEN` is absent (see the runbook § 3.A).
+- **Branch-protection ruleset** — applied in GitHub → Settings → Rules UI;
+  source of truth mirrored in [`branch-protection-policy.md`](contracts/branch-protection-policy.md).
+  Not in code; a successor edits it in the UI.
+- **Repo administration** (visibility / rename / delete) — the
+  `production-visibility` environment gates manual approval; see
+  [`CONTRIBUTING.md`](../CONTRIBUTING.md).
+- **npm trusted-publisher config** — set on npmjs.org for the package, not in
+  this repo.
+
+## "Healthy main" — what good looks like
+
+- Latest `main` commit is green on all required checks for its PR shape
+  (see [`branch-protection-policy.md`](contracts/branch-protection-policy.md),
+  [`ci-green-floor.md`](contracts/ci-green-floor.md)).
+- No drift gate red: `release-drift.yml`, `release-guard.yml`,
+  `check-visibility-drift.yml`, the consistency + claims + proof gates.
+- `docs/CLAIMS.md` resolves (`task check-claims`); `docs/proof.md` is in sync
+  (`task build-proof-check`).
+- No completed roadmap left unarchived in `agents/roadmaps/` (the
+  `roadmap:progress-check` backstop).
+
+## Minimal takeover checklist
+
+1. Get `gh` authenticated as a repo admin; confirm `gh auth status`.
+2. Read [`release-runbook.md`](release-runbook.md) end-to-end.
+3. Confirm the secrets above are present for whichever downstream legs matter.
+4. Cut a `--dry-run` release (`task release -- --dry-run`) to see the pipeline
+   with zero mutations.
+5. When ready, follow the runbook for a real release.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "8.7.0",
+    "version": "8.8.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,
@@ -12,7 +12,7 @@
     "bugs": {
         "url": "https://github.com/event4u-app/agent-config/issues"
     },
-    "homepage": "https://github.com/event4u-app/agent-config#readme",
+    "homepage": "https://event4u-app.github.io/agent-config",
     "keywords": [
         "ai-agent",
         "mcp",

package/src/config/agent-settings.template.yml

@@ -524,13 +524,21 @@ subagents:
   # on  = auto-dispatch delegable tasks without asking (surface the choice
   #       in one line).
   #
-  # Initial SHIPPED default is `ask` on hosts whose capability manifest reports
+  # SHIPPED default is `on` on hosts whose capability manifest reports
   # `subagent_spawn: true`, and `off` on hosts without a subagent primitive.
-  # The shipped default flips toward `on` (host-gated) only behind the Phase-6
-  # benchmark gate of road-to-auto-subagent-orchestration.md — never on an
-  # unmeasured claim. Auto-dispatch is also a no-op wherever the host manifest
-  # reports `subagent_spawn: false`, regardless of this value.
-  auto: ask
+  # Auto-dispatch stays a no-op wherever the manifest reports
+  # `subagent_spawn: false`, regardless of this value.
+  #
+  # The default was `ask` until 2026-07-09, when it was flipped to `on` after a
+  # re-evaluation (agents/settings/contexts/orchestration-default-flip-verdict.md
+  # § 2026-07-09; ADR-117). The flip rests on a bounded-downside argument, NOT a
+  # passed benchmark: delegable slices are already cost-routed to the cheapest
+  # capable tier, classification fires only on real structural signals (never
+  # unstructured or tiny work), and every return is verified — so `on` cannot
+  # delegate frontier-priced or speculative work. `resolveShippedDefault()`
+  # remains the telemetry-driven DEMOTION gate: a measured regression demotes
+  # back to `ask`.
+  auto: on
 
   # Route delegable sub-tasks to the lowest-capable model tier (cost + speed
   # via model downshift). true (default) = downshift per declared model_tier;
@@ -695,6 +703,17 @@ memory:
   # Example: ["api[_-]?key", "/Users/[a-z]+/Library"]
   redact_patterns: []
 
+  # Opt-in compact memory index at session start
+  # (road-to-memory-retrieval-economy Phase 5). When `on`, session_start
+  # injects a compact index of curated entries — id + title + ~tokens,
+  # hard cap 30 rows — through the hot-context hook surface. Bodies are
+  # never injected; the model fetches full entries via memory_get on
+  # demand. Default OFF: the ship-criterion (measured hit-rate gain at
+  # bounded fixed cost) is unproven — off unless proven.
+  #   off = (default) no session-start index.
+  #   on  = inject the compact index (spotlighted as DATA).
+  session_index: "off"
+
 # --- Knowledge cards: global cross-project sharing (ADR-100) ---
 #
 # Structure-grounding v2. Promote *expensive* (remote) knowledge cards from

package/src/scripts/_lib/orchestration_gate.ts

@@ -1,15 +1,19 @@
 /**
- * Default-flip decision gate (Phase 6).
+ * Default-flip / demotion decision gate (Phase 6 → telemetry-demotion).
  *
- * Pure, no-I/O. Encodes the Phase-6 falsification gate: the SHIPPED default for
- * `subagents.auto` flips toward `on` ONLY when a real benchmark shows a net
- * token-or-time win at held quality, and only on hosts with a subagent
- * primitive. Honest-null exit (no win, or quality regressed) keeps the
- * conservative default. Contract:
+ * Pure, no-I/O. Originally the Phase-6 falsification gate: the SHIPPED default
+ * for `subagents.auto` was to flip toward `on` ONLY on a passed benchmark.
+ *
+ * As of 2026-07-09 the shipped default IS `on` on subagent-capable hosts
+ * (ADR-117; agents/settings/contexts/orchestration-default-flip-verdict.md
+ * § 2026-07-09) — flipped on a bounded-downside re-evaluation, not a passed
+ * benchmark. This helper is therefore now the telemetry-driven DEMOTION gate:
+ * a `fail` verdict from accumulated real-world orchestration telemetry demotes
+ * the default back to `ask` (conservative). Contract:
  * `src/agent-src/contexts/execution/orchestration-benchmark-gate.md`.
  *
- * This helper decides; it never runs the benchmark. The measurement is the
- * empirical bench:ab step, authorised + run out of band.
+ * This helper decides; it never runs the measurement. The signal is realized
+ * orchestration telemetry, aggregated + evaluated out of band.
  */
 
 export interface BenchmarkResult {

package/src/scripts/_lib/orchestration_savings.ts

@@ -0,0 +1,127 @@
+/**
+ * Orchestration savings aggregator (pure, no-I/O).
+ *
+ * Aggregates realized orchestration telemetry into a token-savings report.
+ * Consumes the `orchestration` sub-object of audit-log-v1 JSONL lines
+ * (contract: `src/agent-src/contexts/execution/orchestration-telemetry.md`).
+ *
+ * HONEST LIMIT — the telemetry records `token_delta` (net dispatch cost vs the
+ * in-session baseline; negative = saved) but NOT the absolute baseline. A clean
+ * "% of session saved" is therefore NOT derivable from this data alone — only
+ * ABSOLUTE net tokens saved, plus the measured-vs-estimated provenance split.
+ * A percentage would need an absolute-baseline field on the telemetry (see the
+ * report `notes` and the PR's follow-up section).
+ */
+
+export type TokenDeltaProvenance = 'measured' | 'estimated';
+
+/** The `orchestration` sub-object shape we read (subset — additive fields only). */
+export interface OrchestrationRecord {
+    spawn_count?: number;
+    token_delta?: number;
+    token_delta_provenance?: TokenDeltaProvenance;
+    tier_chosen?: string | null;
+    task_class?: string | null;
+    outcome?: string;
+}
+
+/** A parsed audit-log-v1 line (only the fields this aggregator touches). */
+export interface AuditLine {
+    input_kind?: string;
+    orchestration?: OrchestrationRecord;
+}
+
+export interface ProvenanceStat {
+    dispatches: number;
+    /** Σ token_delta for this provenance (negative = net saved). */
+    net_token_delta: number;
+}
+
+export interface SavingsReport {
+    /** Lines carrying an orchestration object with spawn_count > 0. */
+    dispatches: number;
+    total_spawns: number;
+    /** Σ token_delta across all dispatches (negative = net saved). */
+    net_token_delta: number;
+    /** Magnitude of tokens saved (sum of negative deltas, as a positive number). */
+    tokens_saved: number;
+    /** Sum of positive deltas (orchestration that cost MORE than baseline). */
+    tokens_added: number;
+    by_provenance: { measured: ProvenanceStat; estimated: ProvenanceStat };
+    /** tier_chosen → Σ token_delta (negative = net saved on that tier). */
+    by_tier: Record<string, number>;
+    /** task_class → Σ token_delta. */
+    by_task_class: Record<string, number>;
+    /** measured dispatches / dispatches, 0..1 (0 when no dispatches). */
+    measured_share: number;
+    /** Honest caveats about what the number does and does not mean. */
+    notes: string[];
+}
+
+function emptyProvenance(): ProvenanceStat {
+    return { dispatches: 0, net_token_delta: 0 };
+}
+
+/**
+ * Aggregate orchestration telemetry lines into a savings report.
+ *
+ * A line counts as a dispatch only when it carries an `orchestration` object
+ * with `spawn_count > 0` (spawn_count 0 / absent = handled in-session, not a
+ * dispatch). Unknown/absent fields default safely (token_delta → 0, provenance
+ * → estimated) so a pre-extension line never throws.
+ */
+export function aggregateOrchestrationSavings(lines: AuditLine[]): SavingsReport {
+    const report: SavingsReport = {
+        dispatches: 0,
+        total_spawns: 0,
+        net_token_delta: 0,
+        tokens_saved: 0,
+        tokens_added: 0,
+        by_provenance: { measured: emptyProvenance(), estimated: emptyProvenance() },
+        by_tier: {},
+        by_task_class: {},
+        measured_share: 0,
+        notes: [],
+    };
+
+    for (const line of lines) {
+        const o = line.orchestration;
+        if (!o) continue;
+        const spawns = o.spawn_count ?? 0;
+        if (!(spawns > 0)) continue; // in-session, not a dispatch
+
+        report.dispatches += 1;
+        report.total_spawns += spawns;
+
+        const delta = o.token_delta ?? 0;
+        report.net_token_delta += delta;
+        if (delta < 0) report.tokens_saved += -delta;
+        else report.tokens_added += delta;
+
+        // Provenance defaults to `estimated` when unstated (matches the
+        // telemetry contract: estimated is the lossy fallback).
+        const prov: TokenDeltaProvenance = o.token_delta_provenance === 'measured' ? 'measured' : 'estimated';
+        report.by_provenance[prov].dispatches += 1;
+        report.by_provenance[prov].net_token_delta += delta;
+
+        const tier = o.tier_chosen ?? 'unknown';
+        report.by_tier[tier] = (report.by_tier[tier] ?? 0) + delta;
+
+        const cls = o.task_class ?? 'unclassified';
+        report.by_task_class[cls] = (report.by_task_class[cls] ?? 0) + delta;
+    }
+
+    report.measured_share = report.dispatches === 0 ? 0 : report.by_provenance.measured.dispatches / report.dispatches;
+
+    // Honest caveats — always attached so a consumer never over-reads the number.
+    if (report.dispatches === 0) {
+        report.notes.push('No orchestration telemetry yet (0 dispatches). The number accrues as `subagents.auto: on` runs delegate real slices.');
+    } else {
+        report.notes.push('Reports ABSOLUTE net token_delta (negative = saved). A "% of session saved" is NOT derivable — the telemetry records net delta, not the absolute baseline. A percentage needs an absolute-baseline field on the telemetry.');
+        if (report.by_provenance.estimated.dispatches > 0) {
+            report.notes.push(`${report.by_provenance.estimated.dispatches}/${report.dispatches} dispatch(es) use ESTIMATED token_delta (chars/4, lossy). Prefer measured (host usage metadata).`);
+        }
+    }
+
+    return report;
+}

package/src/scripts/build_proof.ts

@@ -107,6 +107,42 @@ function render(): string {
         L.push('Benchmark results are published under `docs/` including measured nulls.');
     }
     L.push('');
+    L.push('**Behavioural-eval coverage — the honest baseline.** Skill *quality* is only');
+    L.push('as good as its measurement. Today **2 of 264** skills carry a behavioural');
+    L.push('`evals.json`, and the highest-traffic / highest-cost tiers (default-surface +');
+    L.push('`rich` + routers, **0 of 35**) are not yet covered. We publish that gap rather');
+    L.push('than imply "264 evaluated skills": coverage is measured per tier');
+    L.push('(`./scripts-run src/scripts/skill_eval_coverage`) and **CI-ratcheted so it can');
+    L.push('only rise** — a merged change can never lower it. Authoring the priority-tier');
+    L.push('evals is gated on per-case human ratification (a generated assertion that');
+    L.push('checks the wrong property is worse than none), so the number grows');
+    L.push('deliberately, not overnight.');
+    L.push('');
+    L.push('**Non-coding domain soundness — scoped, not proven.** The `finance` /');
+    L.push('`founder` / `ops` / `content` profiles sell concrete domain value (DCF,');
+    L.push('runway, RICE, incident command, messaging), but the skills are forged on');
+    L.push('TS/PHP — "promising, not proven" off those stacks. A disclaimer floor');
+    L.push('bounds *liability*, not *correctness*: a skill can be format-correct,');
+    L.push('disclaimered, and still embed a wrong domain assumption. Today **0 of 20**');
+    L.push('default-surface domain skills carry a sourced `domain-truth` fixture');
+    L.push('(`./scripts-run src/scripts/domain_soundness_status`); all are labeled');
+    L.push('`unvalidated` and the validated count is CI-ratcheted. Authoring the');
+    L.push('answer keys needs domain competence (a cited method, not the skill\'s own');
+    L.push('output), so validation lands deliberately — the gap is published, never');
+    L.push('implied away.');
+    L.push('');
+    L.push('**Second-brain substrate — continuity convenience, task-lift unmeasured.**');
+    L.push('The memory substrate is built (working-memory continuity across');
+    L.push('compaction, promotable knowledge cards, contradiction surfacing), but');
+    L.push('whether it beats a no-memory baseline on a reproducible task is **not yet');
+    L.push('measured**. The measurement rig exists — a deterministic multi-session');
+    L.push('recall corpus + scorer (`./scripts-run src/scripts/second_brain_score');
+    L.push('--dry-run`, no model-in-the-loop grading) — but the paired');
+    L.push('`memory-on`/`off`/`placebo` run is spend-bearing and pending. So no');
+    L.push('"second brain" capability claim is made anywhere; the substrate ships as');
+    L.push('continuity convenience until a paired run backs a lift. Boundary vs a');
+    L.push('human PKM is stated in [`docs/second-brain-scope.md`](second-brain-scope.md).');
+    L.push('');
     L.push('## 3. Known limits (published, witness-tested)');
     L.push('');
     const skillGaps = collectSkillGaps();
@@ -164,6 +200,8 @@ function render(): string {
     L.push('task check-refs     # no broken internal references');
     L.push('task check-skill-gaps    # every logged known-limit cites a real witness test');
     L.push('task check-comparison    # every comparison-table "our evidence" pointer resolves');
+    L.push('./scripts-run src/scripts/skill_eval_coverage         # behavioural-eval coverage, per tier');
+    L.push('./scripts-run src/scripts/skill_eval_coverage --check # the ratchet: coverage may not drop');
     L.push('task build-proof-check   # this page is in sync with its sources');
     L.push('```');
     L.push('');

package/src/scripts/chat_history.ts

@@ -43,6 +43,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { _entry_tokens_estimate } from './memory_lookup.js';
+
 import { load_agent_settings } from './_lib/agent_settings.js';
 
 export const DEFAULT_FILE = 'agents/runtime/.agent-chat-history';
@@ -708,6 +710,26 @@ export function read_entries(
         agent?: string | null | undefined;
     } = {},
 ): Entry[] {
+    return read_entries_with_refs(options).map((p) => p.entry);
+}
+
+/**
+ * Like {@link read_entries} but each entry carries its `ref` — the 0-based
+ * ordinal in the file's FULL chronological entry list (header excluded,
+ * counted BEFORE any session/agent/last filter), so a ref from an index row
+ * stays valid regardless of the filters a later call applies. Refs are
+ * stable for the append-only log; file rotation invalidates them (documented
+ * — a ref is a within-file locator, not a durable id).
+ * (road-to-memory-retrieval-economy Phase 3.)
+ */
+export function read_entries_with_refs(
+    options: {
+        last?: number | null | undefined;
+        path?: string | null | undefined;
+        session?: string | null | undefined;
+        agent?: string | null | undefined;
+    } = {},
+): Array<{ entry: Entry; ref: number }> {
     const target = options.path ?? file_path();
     const last = options.last ?? null;
     const session = options.session ?? null;
@@ -715,8 +737,9 @@ export function read_entries(
     if (!_isFile(target)) {
         return [];
     }
-    let entries: Entry[] = [];
+    let pairs: Array<{ entry: Entry; ref: number }> = [];
     const lines = _readLines(target);
+    let ref = 0;
     for (let i = 0; i < lines.length; i++) {
         const line = _strip(lines[i] ?? '');
         if (!line) {
@@ -732,23 +755,72 @@ export function read_entries(
             continue;
         }
         if (_isPlainObject(obj)) {
-            entries.push(obj);
+            pairs.push({ entry: obj, ref });
+            ref += 1;
         }
     }
     if (session !== null) {
-        entries = entries.filter((e) => e.s === session);
+        pairs = pairs.filter((p) => p.entry.s === session);
     }
     if (agent !== null) {
         if (agent === AGENT_UNKNOWN) {
-            entries = entries.filter((e) => !e.agent);
+            pairs = pairs.filter((p) => !p.entry.agent);
         } else {
-            entries = entries.filter((e) => e.agent === agent);
+            pairs = pairs.filter((p) => p.entry.agent === agent);
         }
     }
     if (last !== null && last >= 0) {
-        entries = entries.slice(entries.length - last);
+        pairs = pairs.slice(pairs.length - last);
+    }
+    return pairs;
+}
+
+/**
+ * Timeline anchor: the entries around `ref` in the FULL chronological list —
+ * `before`/`after` neighbours plus the anchor itself. JSONL is chronological,
+ * so this is slicing, not indexing (road-to-memory-retrieval-economy P3).
+ * An out-of-range ref returns [].
+ */
+export function slice_around(
+    path_: string | null,
+    ref: number,
+    before = 3,
+    after = 3,
+): Array<{ entry: Entry; ref: number }> {
+    const all = read_entries_with_refs({ path: path_ });
+    if (ref < 0 || ref >= all.length) {
+        return [];
+    }
+    const start = Math.max(0, ref - Math.max(0, before));
+    const end = Math.min(all.length, ref + Math.max(0, after) + 1);
+    return all.slice(start, end);
+}
+
+/**
+ * Compact index row for a history entry: ref + type tag + timestamp-ish
+ * fields when present + a ~100-char preview + the real-tokenizer cost of
+ * fetching the full entry (same lazy-tokenizer contract as memory_lookup's
+ * index rows).
+ */
+export function history_index_row(pair: { entry: Entry; ref: number }): Record<string, unknown> {
+    const e = pair.entry;
+    const text = typeof e.text === 'string' ? e.text : '';
+    const row: Record<string, unknown> = {
+        ref: pair.ref,
+        t: e.t ?? '',
+        preview: text.slice(0, 100),
+        tokens_estimate: _entry_tokens_estimate(e as Record<string, unknown>),
+    };
+    if (typeof e.s === 'string') {
+        row.s = e.s;
+    }
+    for (const tsField of ['ts', 'time', 'started']) {
+        if (typeof (e as Record<string, unknown>)[tsField] === 'string') {
+            row[tsField] = (e as Record<string, unknown>)[tsField];
+            break;
+        }
     }
-    return entries;
+    return row;
 }
 
 export function read_entries_for_current(