@event4u/agent-config 8.6.0 → 8.8.0

package/docs/decisions/ADR-117-subagents-auto-default-on.md

@@ -0,0 +1,88 @@
+---
+adr: 117
+status: accepted
+date: 2026-07-09
+decision: subagents-auto-default-on
+supersedes: 105
+superseded_by: —
+phase: auto-subagent-orchestration
+type: structural
+---
+
+# ADR-117 — Flip `subagents.auto` shipped default to `on` (host-gated) on bounded-downside re-evaluation
+
+## Status
+
+**Accepted** · 2026-07-09. Amends ADR-105 Decision 2 ("conservative-until-proven
+shipped default `ask`"). Resolved by a re-evaluation under `decision-revisit-gate`
+plus a deep AI-council round (claude-sonnet-4-5 + gpt-4o, 2026-07-08, 4 rounds).
+
+## Context
+
+ADR-105 shipped `subagents.auto: ask` as the conservative default and gated the
+flip to `on` behind a Phase-6 benchmark. That benchmark was found
+**non-producible** in this package's harness (no runtime executes model
+`Task`/`Agent` tool calls), so the 2026-06-26 verdict
+(`orchestration-default-flip-verdict.md`) took the honest-null branch: keep
+`ask`, re-gate on realized telemetry.
+
+That re-gate was **self-locking**: realized telemetry only accrues when the
+layer is `on`, but `on` was withheld pending telemetry. Meanwhile the package
+evolved:
+
+- **Cost-routing shipped.** `road-to-cost-aware-model-routing` (2026-07-08) landed
+  `inferSliceTier` — delegable slices already run on the cheapest capable tier.
+  The system is not cost-blind; only the default was conservative.
+- **The harness now executes subagents.** Host harnesses (Claude Code) execute
+  `Agent`/`Task` calls, so a directional probe is finally possible.
+
+## Decision
+
+The shipped default for `subagents.auto` is **`on`** on hosts whose capability
+manifest reports `subagent_spawn: true`, and `off` on hosts without a subagent
+primitive. `resolveShippedDefault()` is retained as the telemetry-driven
+**demotion** gate.
+
+This is a **bounded-downside** decision, explicitly **not** a passed rigorous
+benchmark. The basis:
+
+1. **Bounded downside.** `on` auto-dispatches only structurally-signalled,
+   cost-routed, verified slices (per `auto-dispatch-classification`). It cannot
+   delegate unstructured, tiny, or frontier-priced work.
+2. **Directional probe (N=2, real, honest limits).** Two live read-only-fan-out
+   delegations this session (~70k, ~86k Sonnet tokens on real work) → ~80%
+   per-task saving vs the inline-Opus counterfactual, outputs verified usable.
+   Small N, single task-type, arithmetic counterfactual — directional only.
+3. **Reversible + monitored.** A measured telemetry regression demotes back to
+   `ask` via `gateVerdict`/`resolveShippedDefault`.
+
+## Consequences
+
+- On subagent-capable hosts, delegable tasks auto-dispatch without a per-task
+  ask; the choice is surfaced in one line.
+- Realized orchestration telemetry now accrues, breaking the deadlock and
+  feeding the demotion gate.
+- Hosts without `subagent_spawn` are unaffected (`off`, no-op).
+- The delegability floor (`SIZE_FLOOR = 1` in `auto_dispatch.ts`) is unchanged
+  and noted as a follow-up refinement — the structural-signal gate already keeps
+  unstructured/tiny work in-session, so it is not load-bearing for this flip.
+
+## Alternatives
+
+- **Keep `ask`, wait for a rigorous benchmark** — rejected: the benchmark is
+  non-producible here and the telemetry re-gate is deadlocked; this is
+  indefinite inertia, not caution.
+- **Flip `on` universally with no cost-routing / floor argument** — rejected:
+  that is the money-losing "flip on unmeasured claim" the deep council warned
+  against; the bounded-downside basis is what makes this flip responsible.
+- **Per-profile default (`on` only for developer)** — rejected for now: no
+  per-profile-default plumbing exists (would be new code); host-gating already
+  scopes the risk.
+
+## References
+
+- ADR-105 — automatic subagent orchestration (Decision 2 amended here).
+- ADR-109 — subagent-v1 contract; ADR-110 — discipline profile.
+- `agents/settings/contexts/orchestration-default-flip-verdict.md` § 2026-07-09.
+- `src/agent-src/contexts/execution/orchestration-benchmark-gate.md` — demotion gate.
+- `src/agent-src/contexts/execution/auto-dispatch-classification.md` — delegability + cost-routing.

package/docs/decisions/INDEX.md

@@ -120,6 +120,7 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-114](ADR-114-commit-policy-iron-law-override.md) | Commit Policy Iron Law Override | — | — | — |
 | [ADR-115](ADR-115-command-cluster-consolidation-phase-4.md) | Command Cluster Consolidation Phase 4 | accepted | 2026-07-08 | — |
 | [ADR-116](ADR-116-memory-tripwire-activation-path.md) | Memory Tripwire Activation Path | accepted | 2026-07-08 | — |
+| [ADR-117](ADR-117-subagents-auto-default-on.md) | Subagents Auto Default On | accepted | 2026-07-09 | 105 |
 | [ADR-200](ADR-200-python-to-typescript-migration.md) | Python To Typescript Migration | accepted | 2026-06-11 | — |
 
 ## Unnumbered (legacy)

package/docs/experiences/content_creator.md

@@ -8,6 +8,8 @@
 Writers, ghostwriters, marketers — draft in someone else's voice, plan a quarter
 of content, ship a launch, render a cinematic AI video.
 
+> **Domain-soundness status (honest).** These skills are forged on TS/PHP; their embedded domain heuristics are **not independently validated**. Until a skill passes a sourced `evals/domain-truth.json` fixture (`./scripts-run src/scripts/domain_soundness_status`), treat its domain correctness as a general-purpose scaffold, not proven practice. The safety floor bounds *liability*, not *correctness*.
+
 ## First three tasks
 
 1. **Write in a voice** — `/ghostwriter` against a public-figure voice profile, or `/post-as` for your own (`.agent-user.md`).

package/docs/experiences/finance.md

@@ -9,6 +9,8 @@ The CFO / fractional finance / FP&A lead — build a DCF, stress-test the plan,
 frame the runway call. Every output carries the finance safety floor (no final
 invest/raise verdict; assumptions + sensitivity + confidence band).
 
+> **Domain-soundness status (honest).** These skills are forged on TS/PHP; their embedded domain heuristics are **not independently validated**. Until a skill passes a sourced `evals/domain-truth.json` fixture (`./scripts-run src/scripts/domain_soundness_status`), treat its domain correctness as a general-purpose scaffold, not proven practice. The safety floor bounds *liability*, not *correctness*.
+
 ## First three tasks
 
 1. **Value it** — `dcf-modeling` walks WACC / terminal-value / 5-year-hold reasoning.

package/docs/experiences/founder.md

@@ -8,6 +8,8 @@
 The solo / early-stage founder — sharpen a fuzzy idea, rank what to build, write
 the why-now slide, get a neutral second opinion.
 
+> **Domain-soundness status (honest).** These skills are forged on TS/PHP; their embedded domain heuristics are **not independently validated**. Until a skill passes a sourced `evals/domain-truth.json` fixture (`./scripts-run src/scripts/domain_soundness_status`), treat its domain correctness as a general-purpose scaffold, not proven practice. The safety floor bounds *liability*, not *correctness*.
+
 ## First three tasks
 
 1. **Sharpen the idea** — `/challenge-me` runs a grill-style interview that turns a vague plan into a copyable pitch.

package/docs/experiences/ops.md

@@ -8,6 +8,8 @@
 RevOps, support, SRE-adjacent — threat-model a change before it ships, command
 the incident when it breaks, build the dashboard that catches it next time.
 
+> **Domain-soundness status (honest).** These skills are forged on TS/PHP; their embedded domain heuristics are **not independently validated**. Until a skill passes a sourced `evals/domain-truth.json` fixture (`./scripts-run src/scripts/domain_soundness_status`), treat its domain correctness as a general-purpose scaffold, not proven practice. The safety floor bounds *liability*, not *correctness*.
+
 ## First three tasks
 
 1. **Threat-model first** — `/threat-model` enumerates abuse cases and trust boundaries before the first line of code.

package/docs/featured-skills.md

@@ -1,6 +1,6 @@
 # Featured Skills
 
-A curated subset of the 264 skills. Three tiers, one per primary audience. Full catalog lives in [`dist/agent-src/skills/`](../dist/agent-src/skills/); see also [`docs/catalog.md`](catalog.md) for the complete index and [`docs/featured-commands.md`](featured-commands.md) for command-level highlights.
+A curated subset of the 267 skills. Three tiers, one per primary audience. Full catalog lives in [`dist/agent-src/skills/`](../dist/agent-src/skills/); see also [`docs/catalog.md`](catalog.md) for the complete index and [`docs/featured-commands.md`](featured-commands.md) for command-level highlights.
 
 > **Eval-gated messaging note.** Until `task bench --corpus non-dev` reports `selection_accuracy >= 0.60` (see `road-to-product-adoption.md` Phase 1), this page is documentation, not marketing. The entries below are the candidates the corpus tests against; their description quality is what the eval validates.
 
@@ -92,4 +92,4 @@ task lint-featured-skills
 
 CI runs this in `taskfiles/ci-fast.yml`. Stale entries (renamed / removed skill or command) fail the build. See [`scripts/lint_featured_skills.py`](../src/scripts/lint_featured_skills.py) for the matcher.
 
-→ Browse all 264 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 172 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)
+→ Browse all 267 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 172 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)

package/docs/getting-started-by-role.md

@@ -2,7 +2,7 @@
 
 > Pick the entry that matches what you do day-to-day. Each section names the three skills you will reach for first and shows whether MCP (no terminal) or CLI (terminal) is the simpler install path for that role.
 
-`agent-config` ships 264 skills, 95 governed rules, and 172 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
+`agent-config` ships 267 skills, 100 governed rules, and 172 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
 
 > **Taglines at a glance →** [`docs/role-experiences.md`](role-experiences.md) — the one-line pitch per role experience, in one table.
 

package/docs/getting-started.md

@@ -134,7 +134,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 95 rules. No configuration needed.
+This is enforced automatically by 100 rules. No configuration needed.
 
 ---
 

package/docs/governance-advantage.md

@@ -33,7 +33,7 @@ the host lacks (a static host gives it no runtime attention guarantee, but a
 runtime-only system gives it nothing at all here). A runtime-only system contributes *nothing* on these hosts.
 
 ### 2. Intent routing, not a 500-artefact dump
-A prompt does not load all 264 skills. `dist/router.json` (91 routed rules, intent →
+A prompt does not load all 267 skills. `dist/router.json` (96 routed rules, intent →
 skill, keyword/phrase/path triggers) carries the right skill on intent. The
 governance value is *selection discipline* — the host gets the relevant rule
 set, not the whole catalogue as context ballast.

package/docs/guidelines/agent-infra/memory-access.md

@@ -22,6 +22,18 @@ agent-config memory:lookup \
 # --envelope v1 for the retrieval-contract envelope.
 ```
 
+**Index-first discipline** (road-to-memory-retrieval-economy — the mirror
+of the MCP tool descriptions, for hosts without MCP): when you expect more
+hits than you need, look up with `--envelope v1 --detail index` first —
+each row carries `id`, `title` and `tokens_estimate` (the cost of fetching
+it) — then fetch ONLY the ids you will actually use via the `memory_get`
+MCP tool (or a full `--detail full` lookup narrowed to the right keys),
+batching multiple ids into one call. For precise single-hit lookups the
+full envelope is already minimal — the paired measurement showed index-
+first COSTS tokens there (honest null pinned in
+`internal/bench/reports/memory-retrieval-run.json`), so reach for index
+mode on broad or exploratory queries, not reflexively.
+
 Every backend MUST return a list of `Hit` with:
 
 | Field | Meaning |

package/docs/proof.md

@@ -26,16 +26,20 @@ evidence pointer, or `task check-claims` fails the build.
 
 | Claim | Kind | Evidence | Resolves |
 |---|---|---|---|
+| The release process is documented as an inheritable runbook + succession doc, and the project's bus-factor (trailing-90-day distinct human reviewers) is tracked and reported truthfully — currently 1, not implied to be more. | qual | `docs/succession.md#trailing 90 days` | ✅ |
 | 172 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | On a weak host (claude-haiku-4-5) the package produces a significant, placebo-controlled discipline lift on scope/downstream traps; on a strong host the same measurement is a published null — the package transplants discipline a weak model lacks, not model intelligence. | quant | `docs/benchmark.md#weak-host-specific` | ✅ |
+| The non-coding domain skills (finance/founder/ops/content) are forged on TS/PHP and labeled unvalidated until they pass a sourced domain-truth fixture; no public prose implies proven domain correctness, and the validated count is CI-ratcheted. | qual | `src/scripts/domain_soundness_status.ts#checkRatchet` | ✅ |
 | On the READ-ONLY FAN-OUT slice family, tier-downshifted subagent dispatch (lite/haiku vs session-tier-proxy sonnet) nets a ≥30% USD-weighted token-cost reduction at held quality — measured 2026-07-08 (n=10 paired live dispatches, 20 telemetry lines): 10/10 exact-match on BOTH arms, 29.4% fewer raw tokens, 76.5% USD-weighted cost reduction at the 3x haiku↔sonnet price ratio. FAMILY-SCOPED — the mechanical-edit family is unmeasured and its downshift (incl. the deferred tier downgrades of existing units) stays gated. Negative control held: an open-ended synthesis/unknown slice never resolves below the session tier (inferSliceTier → medium/inherit, never lite). | quant | `internal/bench/routing-downshift/results-2026-07-08.md#FAMILY-SCOPED PROVE` | ✅ |
 | The lift-carrying essential cut (kernel + downstream-changes) keeps a significant weak-host discipline lift at a fraction of the full load's tokens, and the lift is FAMILY- and HOST-SCOPED — measured on three hosts: claude-haiku-4-5 (weak) shows the family-scoped lift (trapE 0.533→1.000, 7/7 discordant, corpus cost 1.71x); claude-sonnet-4-6 (strong) is a ceiling null; gpt-5-mini (non-Claude weak, codex prompt-prepend surface) FAILED replication with headroom (corpus Δ=+0.024 p=0.70, capability trend n.s. — no harm claimed, injection-surface confound documented). Therefore discipline_profile: auto enables the lift only where measured (vendor-granular unknown_defaults). Non-claims — the balanced router profile was removed after a NULL measurement (p=0.81, n=24); no full-tier recommendation exists; no cross-vendor lift is claimed. | quant | `docs/benchmark.md#REPLICATION FAILED` | ✅ |
+| Behavioural-eval coverage is measured per tier and CI-ratcheted so it can only rise; the current coverage and its gap are published, never implied as "264 evaluated skills". | qual | `src/scripts/skill_eval_coverage.ts#checkRatchet` | ✅ |
 | The whole layer is compiled into host agents with zero runtime daemon. | qual | `docs/contracts/no-runtime-boundary.md#file-first, no-runtime suite` | ✅ |
-| 95 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
-| 264 skills (README hero + feature list). | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 100 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| The second-brain substrate ships as continuity convenience; its cross-session task lift is unmeasured. A deterministic recall scorer + corpus exist (the rig), but no paired run has measured a lift, so no "second brain" capability claim is made until a backed lift entry exists. | qual | `docs/second-brain-scope.md#no measured task-lift` | ✅ |
+| 267 skills (README hero + feature list). | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | Removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries. | qual | `docs/contracts/install-layout.md#JSON-pointer` | ✅ |
 
-**8 backed claim(s)** — all evidence pointers resolve in CI.
+**12 backed claim(s)** — all evidence pointers resolve in CI.
 
 Artefact counts in public prose (skills, commands, governed rules,
 guidelines, personas) are **generated from source and CI-drift-checked**:
@@ -54,6 +58,42 @@ Benchmark results — **including the runs where the package changed nothing**
 live in [`docs/benchmark.md`](benchmark.md). We do not delete a measured null to
 make a number look better; the null is the evidence of honesty.
 
+**Behavioural-eval coverage — the honest baseline.** Skill *quality* is only
+as good as its measurement. Today **2 of 264** skills carry a behavioural
+`evals.json`, and the highest-traffic / highest-cost tiers (default-surface +
+`rich` + routers, **0 of 35**) are not yet covered. We publish that gap rather
+than imply "264 evaluated skills": coverage is measured per tier
+(`./scripts-run src/scripts/skill_eval_coverage`) and **CI-ratcheted so it can
+only rise** — a merged change can never lower it. Authoring the priority-tier
+evals is gated on per-case human ratification (a generated assertion that
+checks the wrong property is worse than none), so the number grows
+deliberately, not overnight.
+
+**Non-coding domain soundness — scoped, not proven.** The `finance` /
+`founder` / `ops` / `content` profiles sell concrete domain value (DCF,
+runway, RICE, incident command, messaging), but the skills are forged on
+TS/PHP — "promising, not proven" off those stacks. A disclaimer floor
+bounds *liability*, not *correctness*: a skill can be format-correct,
+disclaimered, and still embed a wrong domain assumption. Today **0 of 20**
+default-surface domain skills carry a sourced `domain-truth` fixture
+(`./scripts-run src/scripts/domain_soundness_status`); all are labeled
+`unvalidated` and the validated count is CI-ratcheted. Authoring the
+answer keys needs domain competence (a cited method, not the skill's own
+output), so validation lands deliberately — the gap is published, never
+implied away.
+
+**Second-brain substrate — continuity convenience, task-lift unmeasured.**
+The memory substrate is built (working-memory continuity across
+compaction, promotable knowledge cards, contradiction surfacing), but
+whether it beats a no-memory baseline on a reproducible task is **not yet
+measured**. The measurement rig exists — a deterministic multi-session
+recall corpus + scorer (`./scripts-run src/scripts/second_brain_score
+--dry-run`, no model-in-the-loop grading) — but the paired
+`memory-on`/`off`/`placebo` run is spend-bearing and pending. So no
+"second brain" capability claim is made anywhere; the substrate ships as
+continuity convenience until a paired run backs a lift. Boundary vs a
+human PKM is stated in [`docs/second-brain-scope.md`](second-brain-scope.md).
+
 ## 3. Known limits (published, witness-tested)
 
 Each limitation below is stated by the skill itself and carries a witness
@@ -89,6 +129,8 @@ task check-claims   # every markered public claim binds to resolvable evidence
 task check-refs     # no broken internal references
 task check-skill-gaps    # every logged known-limit cites a real witness test
 task check-comparison    # every comparison-table "our evidence" pointer resolves
+./scripts-run src/scripts/skill_eval_coverage         # behavioural-eval coverage, per tier
+./scripts-run src/scripts/skill_eval_coverage --check # the ratchet: coverage may not drop
 task build-proof-check   # this page is in sync with its sources
 ```
 

package/docs/release-runbook.md

@@ -0,0 +1,138 @@
+# Release runbook — cut a correct release from written steps alone
+
+> **Bus-factor doc (road-to-maintainer-bus-factor Phase 3).** The goal: a second
+> maintainer — or the current one after a long gap — can cut a correct release by
+> following THIS document, with no tribal knowledge. Every step maps to a real
+> gate or command in the repo; nothing here is aspirational. Companion:
+> [`succession.md`](succession.md) (secrets, operator-gated steps, "healthy main").
+>
+> **Source of truth for the mechanism:** [`src/scripts/release.ts`](../src/scripts/release.ts)
+> (the shared pipeline) + [`.github/workflows/release.yml`](../.github/workflows/release.yml)
+> (the CI entry) + [`ADR-113`](decisions/ADR-113-ci-native-release-label-trigger.md).
+> If this runbook and those disagree, THEY win and this doc is stale — fix it.
+
+## 0. Mental model
+
+There is **one** release pipeline (`src/scripts/release.ts`) reached by **two**
+entry points that produce the identical result:
+
+| Entry point | How | When to use |
+|---|---|---|
+| **Local** | `task release` (interactive) | You want to watch it, or CI dispatch is unavailable. |
+| **CI-native** | merge a PR labeled `release` / `release:major` / `release:minor` / `release:patch` | The normal path — the merge triggers [`release.yml`](../.github/workflows/release.yml), which runs `release.ts --ci`. |
+
+`release` auto-detects the semver bump from Conventional Commits since the last
+tag; `release:major|minor|patch` forces it. A manual/recovery entry exists via
+the **workflow_dispatch** on `release.yml` (inputs: `bump`, `version`,
+`dry_run`, `resume`).
+
+## 1. Pre-flight (before you start)
+
+- [ ] `main` is green on the latest commit (all required checks — see
+      [`branch-protection-policy.md`](contracts/branch-protection-policy.md)).
+- [ ] Working tree clean, on `main`, `origin/main` in sync
+      (`release.ts` step 1 enforces this and aborts otherwise).
+- [ ] `gh` authenticated (`gh auth status`).
+- [ ] The target tag does **not** already exist (step 1 checks; use `--resume`
+      to recover a partial run — see § 5).
+- [ ] You have read [`succession.md`](succession.md) if any secret-gated
+      downstream (npm publish, cloud deploy) must succeed this release.
+
+## 2. The pipeline — what `release.ts` does (9 steps)
+
+Both entry points run these in order. Each step prints what it will do before
+doing it, so a crash localises to a step.
+
+1. **Preflight** — on `main`, clean tree, `origin` in sync, `gh` present, target
+   tag absent.
+2. **Plan** — compute the new version, parse Conventional Commits since the last
+   tag, render the CHANGELOG section.
+3. **Confirm** — show the preview and ask once. `--yes` skips; `--ci` always
+   requires `--yes` (no terminal in CI).
+4. **Branch + bump** — create `release/X.Y.Z`; update `package.json`,
+   `.claude-plugin/marketplace.json`, `CHANGELOG.md`; then run
+   `task release-prepare` so pack manifests + tool projections pick up the new
+   version (skip this and the PR's own consistency check fails — PR #226
+   post-mortem).
+5. **Commit + push** — commit `release: X.Y.Z`, push the branch, open the PR.
+6. **Wait for CI** — `gh pr checks --watch` (skippable with `--no-wait`).
+7. **Merge** — `gh pr merge --merge --delete-branch`.
+8. **Tag main** — fast-forward `main`, tag the merge commit, push the tag.
+9. **GitHub Release** — `gh release create X.Y.Z --notes <changelog>`. Under
+   `--ci`, also dispatches `release-guard.yml` + `publish-npm.yml` +
+   `cloud-release.yml` (a bot-pushed tag does not trigger them on its own —
+   GitHub's `GITHUB_TOKEN` recursion guard).
+
+## 3. The two ways to run it
+
+### A. CI-native (normal)
+
+1. Open your change PR as usual; get it green + merged into `main`.
+2. To release, add a **`release`** label (or `release:minor` etc.) to a PR and
+   merge it. `release.yml` fires on `pull_request: closed` (merged) and runs
+   `release.ts --ci`.
+3. **Manual checkpoint (only without `RELEASE_PR_TOKEN`):** GitHub's
+   bot-created-PR safeguard queues the release PR's required checks in an
+   approval-required state. Go to the release PR → **"Approve workflows to
+   run"** once. The job's `gh pr checks --watch` then proceeds. This is a
+   deliberate production-release checkpoint, not a bug (see
+   [`branch-protection-policy.md`](contracts/branch-protection-policy.md)).
+   Configuring `RELEASE_PR_TOKEN` removes it (see [`succession.md`](succession.md)).
+4. Watch the `release.yml` run to green. It merges the release PR, tags, cuts
+   the GitHub Release, and dispatches the downstream workflows.
+
+### B. Local (`task release`)
+
+1. `task release` — interactive; it runs the same 9 steps and asks once at
+   step 3. Use `--as minor` / `--version X.Y.Z` to override the bump; `--dry-run`
+   to preview with zero git/gh mutations.
+2. Watch it merge + tag. The tag push triggers `publish-npm.yml` directly (local
+   runs use your user token, so no recursion guard applies).
+
+## 4. Post-release verification
+
+- [ ] `git log --first-parent origin/main -1` shows the `release: X.Y.Z` merge.
+- [ ] `gh release view X.Y.Z` exists with the CHANGELOG notes.
+- [ ] `publish-npm.yml` succeeded (npm has the new version) — see
+      [`succession.md`](succession.md) for the token dependency.
+- [ ] Downstream deploys (`cloud-release.yml`, site) green if this release
+      touched them.
+- [ ] `main` is green post-merge (no drift gate red: `release-drift.yml`,
+      `release-guard.yml`).
+
+## 5. Recovery — a partial or failed release
+
+`release.ts` is **idempotent under `--resume`**: it probes existing state
+(branch, commit, PR, tag, GitHub Release) and skips completed steps.
+
+- Re-run `release.yml` via **workflow_dispatch** with `resume: true`, or locally
+  `task release -- --resume`.
+- Firing the `release` label path twice is a clean no-op (the `--ci`
+  nothing-to-release short-circuit).
+- If a downstream dispatch (npm/cloud) failed but the tag + Release exist, re-run
+  that specific workflow from the Actions tab — do **not** re-cut the release.
+
+## 6. What can go wrong (known checkpoints)
+
+- **Release PR checks stuck "expected"** → the approve-workflows checkpoint in
+  § 3.A step 3. Not a failure; click approve.
+- **Consistency check red on the release PR** → step 4's `task release-prepare`
+  did not run or pack manifests drifted; re-run it on the release branch.
+- **Tag exists but no npm version** → `publish-npm.yml` did not fire or failed;
+  re-run it (§ 5). Never delete + re-push the tag to "retry".
+- **`main`/`origin` diverged mid-release** → stop; resolve the divergence with
+  the `git-workflow` skill's Divergent-State Recovery procedure first, then
+  `--resume`.
+
+## 7. Verify this runbook is not stale
+
+```bash
+# every command / gate this runbook names still exists:
+test -f src/scripts/release.ts && test -f .github/workflows/release.yml
+grep -q "release-prepare" Taskfile.yml
+./scripts-run src/scripts/check_release_pr_shape --help >/dev/null 2>&1 || true
+```
+
+A written-steps-only **dry run** (cut a no-op release following ONLY this doc,
+no tribal knowledge) is the real freshness test — see the roadmap's Phase 3
+dry-run step (maintainer-run; every gap found is a fix to this file).

package/docs/second-brain-scope.md

@@ -0,0 +1,73 @@
+# Second-brain scope — what it is, what it is not, what is measured
+
+> The agent-config "second-brain" substrate is **agent-facing memory**, not a
+> human personal-knowledge-management (PKM) tool. This page states the boundary
+> honestly and binds every capability word to evidence. It follows the
+> `docs/proof.md` § 4 discipline: the category column describes human-PKM only
+> by what is publicly observable, never as a counter-claim to a named project.
+>
+> Roadmap: `road-to-second-brain-delta-proof`. Verdict of record:
+> `agents/settings/contexts/second-brain-delta-verdict.md` (council 2026-07-07).
+
+## The honest status (2026-07-08)
+
+The substrate is **built** (typed knowledge dirs, INDEX generator, retrieval
+protocol, `hot_context_hook` working-memory continuity across compaction,
+`fold_intake`, contradiction surfacing). What is **not yet measured** is the
+*delta*: whether agent-facing memory beats a no-memory baseline on a
+reproducible multi-session task.
+
+- **The measurement rig exists** — a deterministic multi-session recall corpus
+  (`internal/bench/second-brain/corpus/`) + a scorer
+  (`src/scripts/second_brain_score.ts`) with no model-in-the-loop grading. It
+  dry-runs correctly and discriminatingly on hand-written transcripts.
+- **The paired run does not** — the 3-arm `memory-on` / `memory-off` /
+  `placebo` measurement (Phase 2) is spend-bearing and has not been run. So
+  there is **no measured task-lift**, and therefore **no "second brain"
+  capability claim** is made anywhere in public prose. This is the
+  falsifiability lock: the marker never outruns the evidence.
+
+Until the paired run backs a lift, the substrate is documented as **continuity
+convenience** — it carries working memory across sessions and compaction — not
+a proven task-accuracy multiplier.
+
+## What it IS (by design; task-lift unmeasured)
+
+| Capability | What it does | Evidence status |
+|---|---|---|
+| Working-memory continuity | `hot_context_hook` re-injects a bounded, deterministic cache across session boundaries and Claude Code compaction | mechanism shipped; task-lift **unmeasured** |
+| Promotable knowledge cards/pages | typed dirs + INDEX + retrieval protocol, with redaction + team-share gate | mechanism shipped; task-lift **unmeasured** |
+| Contradiction surfacing | a session that contradicts a prior decision is flagged on promote | mechanism shipped; catch-rate **unmeasured** |
+
+## What it is NOT
+
+- **Not a human-browsable knowledge graph.** There is no `.obsidian/` config,
+  no enforced `[[wikilink]]` convention, no link-density value thesis. An
+  editable vault view was evaluated and **rejected** (the dual-write hazard:
+  an external edit that never commits silently diverges the INDEX and
+  recurrence counters). Browsability, if demanded, is a read-only static
+  render — not an editable vault.
+- **Not an Obsidian (or any named PKM) replacement.** The category — a
+  human Markdown graph browsed in an editor, value proportional to
+  link-density, hybrid human-facing retrieval — is a *different product* for a
+  *different consumer* (a person, not an agent). This package writes
+  agent-facing memory; it does not serve a human graph browser.
+- **Not a measured accuracy multiplier** — see the honest status above.
+
+## Interop, not competition (gated on a measured lift)
+
+If — and only if — the Phase-2 paired run shows a real lift, the sanctioned
+next step is a **one-way export** (promoted cards → plain Obsidian-compatible
+Markdown + wikilinks), positioning agent-config as the *writer* and a human PKM
+as the *reader*: complementary, never a replacement. Absent a measured lift,
+the exporter is not built.
+
+## Verify
+
+```bash
+./scripts-run src/scripts/second_brain_score            # corpus summary
+./scripts-run src/scripts/second_brain_score --dry-run  # scorer correct + discriminating, no spend
+```
+
+The paired-run delta, when authorized, pins to
+`internal/bench/reports/` and updates `docs/CLAIMS.md` + `docs/benchmark.md`.

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.6.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",