@event4u/agent-config 8.7.0 → 8.9.0

package/docs/guidelines/agent-infra/emphasis-budget.md

@@ -0,0 +1,45 @@
+# Emphasis budget
+
+Authoring guideline. **This is a review-time discipline, NOT a merge-blocking
+linter** — there is no CI gate; PR review owns the judgment.
+
+## The principle
+
+Emphasis is a currency, and inflation debases it. Reserve the loud channels —
+ALL-CAPS, `## Iron Law` fences, spaced repetition of the same imperative — for
+**asymmetric, irreversible harm**: data loss, credential/secret exposure, a
+safety floor, a legal/compliance breach. When everything shouts, nothing does:
+an over-emphasized doc trains the reader to skim past the caps, so the one caps
+line that guards a `DROP TABLE` loses its signal.
+
+## The discipline
+
+When you add emphasis, be able to answer — in the artifact or the PR — two
+questions:
+
+1. **What specific harm does this prevent?** Name it (not "this is
+   important" — *what* goes wrong, to *whom*, how badly).
+2. **Why is post-hoc correction insufficient?** Emphasis is justified when the
+   harm is irreversible or asymmetric (a wrong send/delete/charge can't be
+   taken back). If a normal-weight sentence + a later fix would do, use normal
+   weight.
+
+If you cannot answer both, down-weight to plain prose.
+
+## Why not a linter
+
+A mechanical caps-quota is unenforceable — semantic substitution ("Critically:
+never…", bold, block quotes) defeats a caps count while keeping the shout — and
+it blocks ready work on a cosmetic metric. The Iron-Law *count* is also a
+denominator artifact: most existing Iron Laws already guard data-loss /
+credential / safety domains, so the raw number is not evidence of inflation.
+Judgment at review time, keyed to the harm-asymmetry test above, is the control.
+
+## Overlap (why a separate guideline)
+
+Distinct from [`preservation-guard`](../../../src/rules/preservation-guard.md)
+(preserve existing emphasis through a transform — this governs *adding* it),
+[`size-enforcement`](../../../src/rules/size-enforcement.md) (line budgets, not
+emphasis weight), and [`token-budget-discipline`](../../../src/rules/token-budget-discipline.md)
+(load cost, not signal-to-noise). None owns the emphasis-rationing judgment;
+this guideline does.

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/guidelines/agent-infra/simplicity-and-goal-demos.md

@@ -0,0 +1,151 @@
+# Simplicity and Goal Discipline — wrong/right demos
+
+Recognition surface for [`minimal-safe-diff § Anti-over-engineering`](../../src/rules/minimal-safe-diff.md)
+(own-orphan cleanup, speculative-complexity bans) and the goal-driven
+execution clause in `think-before-action`. Per council convergence
+(2026-07-10): the demos ARE the enforcement — an agent that has never seen
+the violation cannot recognize it, no matter how crisp the checklist question.
+Match your diff against the *right* column before presenting.
+
+## 1. Over-abstraction vs. one function
+
+**Ask:** "Add a function to calculate a percentage discount."
+
+**Wrong — Strategy pattern for a single caller (PHP):**
+
+```php
+interface DiscountStrategy { public function calculate(float $amount): float; }
+final class PercentageDiscount implements DiscountStrategy { /* … */ }
+final class FixedDiscount implements DiscountStrategy { /* … */ }
+final readonly class DiscountConfig { /* strategy, minPurchase, maxDiscount */ }
+final class DiscountCalculator { /* 30+ lines of orchestration */ }
+```
+
+**Right — one function until the second discount type is real:**
+
+```php
+function calculateDiscount(float $amount, float $percent): float
+{
+    return $amount * ($percent / 100);
+}
+```
+
+**Why:** No second caller, no second strategy → no abstraction. When the
+second type genuinely arrives, refactor then (`prefer-enums-over-literals` /
+Strategy sniff test governs that moment). The wrong version is not "bad
+code" — it is *premature* code: harder to read, more surface to test, and
+speculative until the requirement exists.
+
+## 2. Speculative features vs. just-what-was-asked
+
+**Ask:** "Save user preferences to the database."
+
+**Wrong — options nobody requested (TypeScript):**
+
+```ts
+class PreferenceManager {
+  constructor(db: Db, cache?: Cache, validator?: Validator) { /* … */ }
+  save(userId: number, prefs: Prefs,
+       opts: { merge?: boolean; validate?: boolean; notify?: boolean } = {}) {
+    // merging, validation, cache write, notification fan-out — all unasked
+  }
+}
+```
+
+**Right — the ask, nothing else:**
+
+```ts
+async function savePreferences(db: Db, userId: number, prefs: Prefs) {
+  await db.query('UPDATE users SET preferences = $1 WHERE id = $2',
+    [JSON.stringify(prefs), userId]);
+}
+```
+
+**Why:** Every optional parameter with one call site, every "flexibility"
+flag, and every handler for a scenario that cannot occur is speculative
+complexity. Add caching when performance data demands it, validation when bad
+data appears, merging when the requirement lands.
+
+## 3. Drive-by refactor vs. surgical diff
+
+**Ask:** "Fix the bug where an empty email crashes the validator."
+
+**Wrong:** the fix PLUS improved email regex, new username length checks,
+rewritten comments, and a fresh docstring — four changes, one was asked.
+
+**Right:** only the lines that make the empty-email case safe change; every
+other line of the function is byte-identical.
+
+**Why:** Every changed line must trace to the stated task
+(`minimal-safe-diff`). The "improvements" belong in a follow-up proposed via
+`active-remediation`'s note-and-ask ladder — not smuggled into the bug fix.
+
+## 4. Style drift vs. match-existing-style
+
+**Ask:** "Add logging to the upload function."
+
+**Wrong:** the diff adds logging AND flips quote style, adds type hints,
+reshapes the boolean return, reflows whitespace — the reviewer can no longer
+see the logging change.
+
+**Right:** logger import + three log lines, inserted in the file's existing
+style (its quoting, its spacing, its return pattern), even where you would
+personally write it differently.
+
+**Why:** Style consistency is a repo property, not a per-diff taste decision.
+A diff that reformats while changing behavior hides the behavior change.
+
+## 5. Own-orphan vs. pre-existing dead code
+
+**Ask:** "Replace the legacy formatter call in `processA` with the new one."
+
+**Wrong (too little):** `processA` no longer calls `legacyFormat()`, but the
+now-unused import and the helper it alone referenced stay behind — the diff
+shipped its own litter.
+
+**Wrong (too much):** while in the file, the agent also deletes
+`oldHelper()`, which `processB` — untouched by this diff — still references
+in another module, or which was already orphaned *before* this task.
+
+**Right:** remove exactly the imports/variables/functions whose **last
+reference disappeared in a file this diff touched**; anything still
+referenced from untouched files — or orphaned before the task — is
+pre-existing debt: mention it, don't delete it.
+
+**Why:** The boundary is mechanical (grep after editing), so there is no
+judgment call to rationalize — see
+[`minimal-safe-diff § Own-orphan cleanup`](../../src/rules/minimal-safe-diff.md#own-orphan-cleanup).
+
+## 6. Vague plan vs. verifiable per-step plan
+
+**Ask:** "Add rate limiting to the API."
+
+**Wrong — unverifiable narration:**
+
+```
+1. Review the code
+2. Identify issues
+3. Implement rate limiting
+4. Test the changes
+```
+
+**Right — every step carries its check:**
+
+```
+1. In-memory limit on one endpoint → verify: 11th request in a minute → 429 (test)
+2. Extract to middleware, all endpoints → verify: limit fires on /users AND /posts; existing endpoint tests stay green
+3. Shared store backend → verify: counter survives app restart; two instances share the count
+```
+
+**Why:** A step without a `verify:` is an assumption. Strong criteria let the
+loop run independently (`verify-before-complete` then has something to
+check); "make it work" guarantees clarification churn after the fact instead
+of before.
+
+## Key insight
+
+The wrong versions are not obviously wrong — they follow known patterns and
+"best practices". The failure is **timing**: complexity added before the
+requirement exists costs comprehension, bugs, and test surface today for a
+tomorrow that may never come. Solve today's problem simply; refactor when the
+second requirement is real.

package/docs/guidelines/agent-infra/tool-description-as-policy.md

@@ -0,0 +1,35 @@
+# Tool description as policy
+
+Authoring guideline for skills, commands, and MCP tools. Shared block — cited
+from [`skill-writing`](../../../src/skills/skill-writing/SKILL.md),
+[`command-writing`](../../../src/skills/command-writing/SKILL.md), and
+[`mcp-builder`](../../../src/skills/mcp-builder/SKILL.md).
+
+## The principle
+
+Policy that governs *how a tool is used* belongs **inside the tool's own
+description**, where it fires at the decision point the model is already
+reading — not in always-on prose the model may not have loaded when it reaches
+for the tool. The description is the highest-signal, best-timed place to encode
+usage policy.
+
+## What to encode in the description
+
+- **Workflow sequencing.** If tool B must follow tool A ("call `memory_lookup`
+  with `detail:index` FIRST, then `memory_get` the ids"), say so in B's
+  description, not in a separate rule.
+- **Preconditions.** What must be true before the tool is called (a built
+  artifact present, a prior step run) — stated where the model chooses to call.
+- **ID / output provenance.** When the tool returns handles (ids, paths, PR
+  numbers), instruct: **copy them verbatim from the tool result, never from
+  memory** — context decay silently corrupts a remembered id.
+- **A mandatory "why" intent field.** Require the caller to state the intent of
+  the call; a tool that forces "why am I calling this" cuts reflexive misuse.
+- **Turn-end contracts.** If the tool ends the turn or hands off, the
+  description says so — the caller does not discover it after the fact.
+
+## Why here, not as an always-on rule
+
+An always-on rule pays context cost on every turn and may be evicted before the
+decision; the description is loaded exactly when the tool is under
+consideration. Encode the policy at the point of use.

package/docs/guidelines/design-canon.md

@@ -60,3 +60,4 @@ Pull when: choosing or auditing an icon library.
 - `docs/guidelines/design-antipatterns.md` — the anti-slop catalog (T7 default-font tell, C1/C5 palette tells) this canon helps you escape.
 - `brand-source-of-truth` / `brand-consistency` — the precedence this index obeys.
 - `design-intelligence` — the consumer that surfaces these on a brief signal.
+- **Reference, don't vendor** (`domain-adoption-policy`): palette hex tables, font-width CSVs, easing/motion constant libraries, print-CSS recipes, and device-frame recipes are **referenced from maintained upstreams, never forked** into this suite — a vendored data table rots, fork-drifts, and couples the suite to one aesthetic. Corpus assets (palettes, easing tables, device frames) stay upstream references, not forks.

package/docs/proof.md

@@ -26,16 +26,24 @@ 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` | ✅ |
+| The retrieval economy cuts always-loaded context tokens ~65.6% measured against the FULL always-loaded projection — 98,529 → 33,897 tokens (eager rule load + skill/command descriptions + MCP schemas, thin-flipped). Method: `agent-config benchmark` over the pinned token baseline; the baseline is the honest "what the user pays if everything loads eagerly", NOT a synthetic full-corpus strawman (council Q4). | quant | `internal/bench/reports/token-baseline.json#eager_rule_load` | ✅ |
 | 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` | ✅ |
+| A hand-rolled, dependency-free BM25 + trigram lexical index resolves the "recalls but does not rank" gap: on the retrieval-precision corpus (9 keyword-overlapping-confuser tasks) it drives the mean top tie-set from 3.333 (the `_score` bucket scorer) to 1.0 — every needed decision uniquely top-ranked — with precision@1 and precision@5 unchanged at 1.0. Method: deterministic, model-free re-ranking of the SAME retrieved entry set; both scorers measured over the identical store via `measure_lexical_ranking.ts`. | quant | `internal/bench/reports/lexical-ranking.json` | ✅ |
 | 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` | ✅ |
+| 102 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| On a deterministic multi-session recall corpus, the memory substrate produces a measured, placebo-controlled recall lift — memory-on 27/27 vs no-memory 10/27 and vs equal-byte placebo 9/27 (claude-haiku-4-5, n=9 tasks x 3 seeds, sign test p=0.031 for BOTH pairings). Scoped honestly: this is the context-value upper bound (perfect retrieval on a one-fact-per-task corpus), not retrieval precision under a large store. | quant | `internal/bench/reports/second-brain-delta.json` | ✅ |
+| Removing the perfect-retrieval assumption, the substrate's REAL keyword retrieval recalls the needed decision into the top-5 under keyword-overlapping confusers (precision@5 9/9) and the model disambiguates it from the co-injected confusers — retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27 (claude-haiku-4-5, 9 tasks x 3 seeds, sign test p=0.008 both). Named limit: retrieval RECALLS but does not RANK (mean tie-set 3.3, ties broken by store order, not relevance) — the discrimination gap that motivates the SQLite-FTS5 activation path (ADR-116) at larger scale. | quant | `internal/bench/reports/second-brain-retrieval.json` | ✅ |
+| Every artifact the package ships — source AND the condensed projection that reaches consumers — is machine-scanned in CI for hidden-Unicode, mixed-script-confusable, and instruction-smuggling payloads (the rules-file-backdoor class); a finding blocks the release before `npm publish`, not just the merge. | qual | `.github/workflows/publish-npm.yml#lint_agent_security` | ✅ |
+| 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.
+**16 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 +62,53 @@ 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 **5 of 20**
+default-surface domain skills carry a sourced `domain-truth` fixture
+(`./scripts-run src/scripts/domain_soundness_status`); the rest are labeled
+`unvalidated` and the validated count is CI-ratcheted. The fixtures landed
+so far are the **deterministic** targets (runway, unit-economics, DCF,
+forecasting, scenario band/sensitivity), whose answer keys are computed
+from cited standard formulas — never the skill's own output; the
+**rubric** targets (incident command, messaging, fundraising, editorial)
+need domain-competent grounding and remain unvalidated, so validation
+lands deliberately — the gap is published, never implied away.
+
+**Second-brain substrate — measured recall lift, honestly bounded.** On a
+deterministic multi-session recall corpus, the memory substrate beats a
+no-memory baseline AND an equal-byte placebo: memory-on **27/27** vs
+no-memory **10/27** vs placebo **9/27** (claude-haiku-4-5, 9 tasks × 3
+seeds, sign test **p = 0.031** for both pairings) — a real,
+placebo-controlled lift (`internal/bench/reports/second-brain-delta.json`).
+Scoped, not oversold: this is the context-value upper bound (perfect
+retrieval on a one-fact-per-task corpus), NOT retrieval precision under a
+large store; the lift concentrates exactly where memory is the only source
+and ties where the prompt self-contains the fact. Boundary vs a human PKM,
+and why the Obsidian export stays declined, are in
+[`docs/second-brain-scope.md`](second-brain-scope.md).
+
+A follow-up removed the perfect-retrieval assumption: against a store of
+keyword-overlapping confusers the REAL retrieval recalls the needed
+decision into the top-5 (9/9) and the model disambiguates it — retrieval-on
+**27/27** vs no-memory **5/27** and vs placebo **5/27** (p=0.008 both). The
+honest limit: the keyword scorer recalls but does not rank (mean tie-set
+3.3), which is the SQLite-FTS5 activation signal (ADR-116) at scale.
+
 ## 3. Known limits (published, witness-tested)
 
 Each limitation below is stated by the skill itself and carries a witness
@@ -89,6 +144,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,116 @@
+# 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-09 — measured PASS, bounded)
+
+The substrate is **built** (typed knowledge dirs, INDEX generator, retrieval
+protocol, `hot_context_hook` working-memory continuity across compaction,
+`fold_intake`, contradiction surfacing), and the cross-session recall *delta*
+is now **measured** — a real, placebo-controlled lift, honestly scoped.
+
+- **The measurement rig** — 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.
+- **The paired run (Phase 2)** — `memory-on` / `memory-off` / `placebo` on a
+  fixed host (claude-haiku-4-5), 9 tasks × 3 seeds (81 calls). Result:
+  memory-on **27/27**, no-memory **10/27**, equal-byte placebo **9/27**;
+  memory-on beats BOTH, sign test **p = 0.031** for each pairing → **PASS**.
+  Full report: `internal/bench/reports/second-brain-delta.json`
+  (claim `second-brain-recall-lift`).
+- **Where the lift lives** — it concentrates on the retrieval-accuracy tasks
+  where the prior fact is available ONLY from memory (memory-on 3/3, baseline
+  0/3). It **ties** on the three tasks whose k+1 prompt already self-contains
+  the signal (a correction stated in-prompt, or a contradiction the prompt
+  names) — exactly where memory is not the only source. memory-on never loses.
+
+### The scoping caveat (stated, not buried)
+
+The Phase-2 delta is the **context-value upper bound**: the corpus is
+one-fact-per-task, so memory-on injects the exact fact (perfect retrieval). It
+shows that **the right prior fact, surfaced, lets the model answer — and that
+this beats both no memory and equal-byte noise** (the placebo isolates mechanism
+from mere extra context).
+
+**The retrieval-precision follow-up removed the perfect-retrieval assumption**
+(2026-07-09, claim `second-brain-retrieval-precision`,
+`internal/bench/reports/second-brain-retrieval.json`). Against a populated store
+whose distractors deliberately share query keywords with the needed decision,
+the REAL `memory_lookup` retrieval recalls the needed decision into the top-5 in
+**9/9** cases, and the model disambiguates it from the co-injected confusers —
+**retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27**
+(sign test p=0.008 both). **Named limit (honest):** the keyword scorer
+**recalls but does not rank** — mean tie-set 3.3 entries share the top score,
+ties broken by store order, not relevance. So recall into the top-k holds *at
+this scale*; once more than k entries share a keyword it would degrade — which
+is exactly the discrimination gap the SQLite-FTS5 activation path (ADR-116)
+exists to close. The public claims are scoped to exactly this.
+
+**Second named limit (separator recall, found 2026-07-10 in a labelled replay
+of real maintainer queries):** `_score()` matches raw substrings, so a query
+key whose token separator differs from the stored field misses entirely —
+`ai_council`, `roadmap-progress`, `force-push` score 0 against space-normalized
+`key` fields that spaced variants (`ai council`) hit at 0.8. The precision
+measurement above did not probe this class (its confusers share exact
+keywords), so it is scoped OUT of the precision claim. Deliberately not
+hot-fixed: naive scoring is locked until the scale tripwire (the archived
+retrieval-economy roadmap's D5), and the FTS5 unicode61 tokenizer splits on
+separators, closing this structurally at activation time. Reproduce:
+`memory_lookup --types product-rules --key "ai_council"` vs `--key "ai council"`
+against any populated store.
+
+## What it IS (measured lift, bounded as above)
+
+| 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; recall lift **measured (bounded PASS)** |
+| Promotable knowledge cards/pages | typed dirs + INDEX + retrieval protocol, with redaction + team-share gate | mechanism shipped; recall lift **measured (bounded PASS)** |
+| Contradiction surfacing | a session that contradicts a prior decision is flagged on promote | mechanism shipped; ties in-prompt, lift where memory is the only source |
+
+## 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 an unbounded accuracy multiplier** — the recall lift is measured but
+  scoped to the context-value upper bound (see honest status), not proven
+  retrieval precision under a large store.
+
+## Interop, not competition (export declined, on the record)
+
+The Phase-2 paired run did show a real (bounded) lift, which unlocks the
+optional one-way export (promoted cards → Obsidian-compatible Markdown). It is
+**deliberately not built**: the delta-verdict of record
+(`agents/settings/contexts/second-brain-delta-verdict.md`, council 2026-07-07)
+**rejected** Obsidian compatibility — the dual-write hazard (an external edit
+that never commits silently diverges the INDEX + recurrence counters) outweighs
+the browsing convenience, and the measured lift is a bounded context-value
+result, not a retrieval-precision proof that would justify a new external
+surface. If a human-PKM bridge is ever wanted, the sanctioned path is a
+read-only static render, not an editable vault. Positioning stays: agent-config
+writes agent-facing memory; it does not replace a human PKM.
+
+## 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`.