@event4u/agent-config 9.8.0 → 9.9.0

package/docs/release-runbook.md

@@ -1,141 +0,0 @@
-# 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.
-- [ ] The release satisfies [`release-sizing.md`](contracts/release-sizing.md) —
-      one primary product goal, and a `Rollback:` line for every new /
-      substantially reworked subsystem (gate: `src/scripts/lint_changelog_rollback.ts`).
-
-## 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/role-experiences.md

@@ -1,19 +0,0 @@
-# Role experiences — taglines at a glance
-
-> **Generated** by `scripts/generate_role_experiences_catalog.py` from
-> `agents/roles/<role>/index.md` — do NOT hand-edit. Taglines are the
-> existing role-level strings (validated by `lint_role_experiences.py`,
-> rendered in the GUI workspace); this page surfaces them in a catalog.
-
-Each row links to the full role experience (persona · three first tasks ·
-packs). The catalog never duplicates the body — see
-[`docs/contracts/role-experience.md`](contracts/role-experience.md).
-
-| Role | Tagline | Status |
-|---|---|---|
-| [Consultant / advisor](../agents/roles/consultant/index.md) | Client briefs, investor memos, and deck outlines — refined before the meeting, not rewritten after. | `beta-internal` |
-| [Content creator](../agents/roles/content-creator/index.md) | From a one-line idea to a stitched short — voice-locked, character-locked, provider-agnostic. | `beta-internal` |
-| [Galabau owner](../agents/roles/galabau/index.md) | Drafting customer offers and project briefs without a project manager between you and the document. | `beta-internal` |
-| [Team leader](../agents/roles/leadership/index.md) | Summarise weekly status, write the risk memo, structure the decision before the meeting. | `beta-internal` |
-| [Sales rep](../agents/roles/sales/index.md) | Answer customer questions, draft offers, and prep discovery calls — voice-locked, structured, fast. | `beta-internal` |
-| [Support agent](../agents/roles/support/index.md) | Summarise the ticket, draft the reply, flag the escalation — without rewriting the customer's words. | `beta-internal` |

package/docs/safety.md

@@ -1,30 +0,0 @@
-# Data governance & domain safety
-
-`agent-config` ships **12 domain-safety rules** (`src/rules/domain-safety-*.md`) that act as a per-domain output floor — PII redaction, disclaimer requirements, and retention guidance. Rules fire automatically via the router when their triggers match.
-
-## Surface → rule(s) → floor
-
-| Surface | Rule(s) | Floor |
-|---|---|---|
-| Support / CRM drafts | `domain-safety-pii-support` · `domain-safety-retention-support` | Redact customer names, emails, phones, account IDs to placeholders before output |
-| Finance / invoicing | `domain-safety-pii-finance` · `domain-safety-retention-finance` | Redact counterparty PII and bank identifiers; flag retention under audit hold |
-| Recruiting | `domain-safety-pii-recruiting` | Redact candidate PII from notes, scorecards, rejection emails |
-| Marketing testimonials | `domain-safety-pii-marketing` | Require consent record before customer-identifying copy ships |
-| Legal · financial · medical · consulting drafts | `domain-safety-disclaimer-*` | "Not legal/financial/medical advice" disclaimers; refuse diagnostic / dosage / specific tax positions |
-| Logs · exports | `domain-safety-logging-pii-floor` · `domain-safety-export-redact` | No raw PII in logs or exports; allowlist-driven structured fields only |
-
-## How the floor is enforced
-
-- Each rule declares `applies_to_user_types:` in frontmatter — rules load only when the matching user-type is active (forward-compatible with the user-types axis shipping in `step-9-user-types-axis`).
-- Each rule routes to `skill:privacy-review` as the baseline deeper-regime check (GDPR · CCPA · HIPAA).
-- The set is opt-in by domain, never overrides higher Iron Laws (`non-destructive-by-default`, `commit-policy`, `scope-control`).
-
-## Related skills
-
-- [`privacy-review`](../src/skills/privacy-review/SKILL.md) — end-to-end data-flow review for a regulatory regime (GDPR / CCPA / HIPAA).
-- [`data-handling-judgment`](../src/skills/data-handling-judgment/SKILL.md) — classification, retention, cross-border transfer, DSR workflow.
-
-## See also
-
-- [`non-destructive-by-default`](../.augment/rules/non-destructive-by-default.md) — Hard Floor that overrides every domain-safety carve-out.
-- [`security-sensitive-stop`](../.augment/rules/security-sensitive-stop.md) — threat-model before touching auth / billing / tenant boundaries / uploads.

package/docs/second-brain-scope.md

@@ -1,116 +0,0 @@
-# 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`.

package/docs/self-review-gate.md

@@ -1,65 +0,0 @@
-# Self-review gate (dogfooded PR review)
-
-The package reviews its own PRs with the exact machinery it ships —
-[`adversarial-review`](../src/skills/adversarial-review/SKILL.md) +
-[`agent-security-review`](../src/skills/agent-security-review/SKILL.md) — via
-[`.github/workflows/self-review-gate.yml`](../.github/workflows/self-review-gate.yml)
-and [`src/scripts/self_review_gate.ts`](../src/scripts/self_review_gate.ts).
-
-`road-to-maintainer-bus-factor` Phase 1.
-
-## Current status — ADVISORY, inert without a secret
-
-This is an **honest floor, not independent human review**, and today it is
-**advisory + inert-without-secret**. Do not read it as "every PR is
-AI-reviewed" — that is only true once the maintainer arms it (below).
-
-| Job | Runs | Spend | Blocks merge |
-|---|---|---|---|
-| `gate-dry-run` | every PR | none (no API) | never — prints the review plan only |
-| `live-advisory` | every PR **iff** `ANTHROPIC_API_KEY` is set | one review call | never — posts findings, records what *would* block |
-
-Without the `ANTHROPIC_API_KEY` repo secret, `live-advisory` is a **logged
-no-op** (never a failing check) — exactly the `cross-model-canary.yml` pattern.
-
-## The teeth (defined + wired, not yet armed)
-
-`self_review_gate.ts` exposes pure, unit-tested:
-
-- `classifyBlocking(finding)` — a finding is merge-blocking **iff**
-  `kind ∈ {security, claim}` **and** `severity ∈ {critical, high}`. Style and
-  correctness findings, and low/medium security findings, advise only. (Council
-  2026-07-08, claude-sonnet-4-5 + gpt-4o: a 100 %-blocking gate at
-  solo-maintainer token cost gets ignored or gamed — block only on the narrow
-  security/claim × high+ intersection.)
-- `gateVerdict(findings, {enforce})` — mirrors
-  `check_quality_regression.gateVerdict`: `0` pass / `2` block. Shipped
-  `enforce: false` (advisory always returns `0` and reports the would-block
-  set).
-
-## Escalation on large / claim-affecting diffs
-
-The two in-session lenses are a floor. A **large** diff (≥ 400 changed lines
-across reviewable files) or one that touches a **claim-affecting surface**
-(`docs/CLAIMS.md`, `docs/proof.md`, `docs/comparison.yaml`, or `README.md`)
-warrants the full `ai-council` advisor panel — a spend-bearing multi-model run.
-
-Per blocker `self-review-gate-cost`, the paid council stays governed by the
-standing spend-authorization discipline **at run time**. So the gate does not
-fire council calls itself: `escalationReasons(files, changedLines)` (pure,
-unit-tested) DETECTS the condition, the dry-run plan prints it, and the posted
-review RECOMMENDS a maintainer `/council:pr` run. Detection is deterministic
-and zero-spend; the multi-model run is the maintainer's run-time act.
-
-## Arming it (maintainer, one flip)
-
-1. Add the `ANTHROPIC_API_KEY` repo secret (per-PR budget sign-off) — turns
-   `live-advisory` from no-op into a real dogfooded review.
-2. Pass `--enforce` in the live job to arm the teeth (block on
-   security/claim × high+).
-3. Require the `Self-review gate` check in branch protection
-   (`road-to-maintainer-bus-factor` Phase 2) so even solo merges pass the gate.
-4. Record the floor CLAIM on the proof page **once it is live** — not before
-   (an inert gate is not a passed gate).
-
-Blocker `self-review-gate-cost` (maintainer-owned) gates steps 1–2.

package/docs/setup/enterprise-and-offline.md

@@ -1,201 +0,0 @@
-# Enterprise & offline installation
-
-> **Status:** experimental · contract-shaped output of
-> `agents/roadmaps/road-to-distribution-maturity.md` Phase 2. Four
-> documented happy-paths for environments where the public npm
-> registry is not freely reachable from the developer's machine, plus
-> a "no-internet developer" runbook.
-
-## Why no Composer fallback
-
-Re-introducing a Composer-published distribution was evaluated in the
-Phase 0 council session
-(`agents/runtime/council/questions/composer-fallback-feasibility.md`) and
-**rejected** on three grounds:
-
-1. **Lock-shape mismatch.** `installed.lock` is npm-shaped (flat dep
-   model + npm pin in `.agent-settings.yml`). A Composer fallback
-   would need either a parallel manifest (breaks the "lock is
-   canonical" invariant) or a translation layer (defeats the
-   "minimal" claim).
-2. **Dual-distribution attack surface.** Two pipelines means two
-   SBOMs, two CVE response surfaces, two signing roots. Supply-chain
-   risk doubles for a fallback most operators will never use.
-3. **"Minimal fallback" is an oxymoron.** Partial functionality
-   shipped on a parallel pipeline confuses operators more than it
-   helps — the failure mode of a half-working Composer install is
-   worse than a documented npm-only path.
-
-The supported alternative is the **four-path enterprise/offline
-matrix** below, all of which keep npm as the single distribution
-channel.
-
-## Path A — pinned-npx via internal registry
-
-For environments where the public registry is unreachable but an
-internal mirror (Verdaccio, Nexus, JFrog, Sonatype) is configured:
-
-```bash
-# .npmrc at repo root or ~/.npmrc
-registry=https://npm.internal.example.com/
-@event4u:registry=https://npm.internal.example.com/
-always-auth=true
-```
-
-Pin the consumed version in the consumer project's
-`.agent-settings.yml`:
-
-```yaml
-# .agent-settings.yml
-agent_config_version: "2.6.1"  # matches the version your mirror has indexed
-```
-
-`scripts/install.py` reads `agent_config_version` at install time and
-records it in `~/.event4u/agent-config/installed.lock` per ADR-007.
-The registry-mirror caveat: your mirror **must** index the
-`@event4u/agent-config` scope before the first `npx` call — `npx`
-does not transparently fall back from a private mirror to the public
-registry.
-
-> **Consumer npm-pinning ≠ release-shape pinning.** This path pins
-> what the consumer's `npx` resolves to. The package's own release
-> cadence (semver, tags, deprecation windows) is not pinned here per
-> `.augment/rules/scope-control.md` § "no version pinning in
-> roadmaps". The `agent_config_version` field is a consumer choice.
-
-## Path B — offline cache strategy
-
-For environments where the developer's machine has no network egress
-at all but a pre-staged npm cache is delivered out-of-band:
-
-```bash
-# On a machine with internet access:
-npm cache add @event4u/agent-config@2.6.1
-tar -czf agent-config-npm-cache.tgz ~/.npm/_cacache
-
-# On the offline machine:
-tar -xzf agent-config-npm-cache.tgz -C ~/
-npx --prefer-offline @event4u/agent-config init
-```
-
-Corepack-pinning the npm version makes the cache reproducible across
-developers:
-
-```bash
-corepack enable
-corepack prepare npm@10.5.0 --activate  # whatever version your cache was built with
-```
-
-`agent_config_version` in `.agent-settings.yml` must match the cached
-version exactly — otherwise `npx` will try (and fail) to resolve a
-different version from the registry.
-
-## Path C — CI-safe install pattern
-
-CI agents (GitHub Actions runners, GitLab runners, Jenkins agents
-behind a corporate proxy) get a narrower happy-path:
-
-- **Cached tarball** in the runner's artifact store
-  (`actions/cache@v4` or equivalent), keyed on
-  `agent_config_version`.
-- **`npm install --offline`** against the cache so the runner never
-  hits the registry.
-- **`scripts/install.py validate`** instead of `init` — `validate`
-  re-reads `installed.lock` and checks the worktree matches; `init`
-  scaffolds tool directories which a CI agent typically does not
-  need.
-- **No global writes.** CI runners are ephemeral; the
-  `~/.event4u/agent-config/installed.lock` write is harmless but the
-  CI job should not rely on it persisting between runs.
-
-## Path D — verified-offline install (`scripts/hermetic-install.sh`)
-
-> **Naming note.** The file name is `scripts/hermetic-install.sh` for
-> roadmap continuity (Phase 2 Step 5). The **semantic** per the
-> Anthropic council verdict is **verified-offline install** — the
-> checksum manifest is delivered via a separate channel (not bundled
-> in the tarball), so the trust model is not circular. "Hermetic" is
-> used in the colloquial sense (reproducible + verifiable), not the
-> Bazel-strict sense.
-
-For air-gapped or strict-supply-chain environments where (a) network
-egress is fully blocked, (b) tarball integrity must be verifiable
-against an external manifest, and (c) installation must be auditable
-end-to-end:
-
-```bash
-# 1. Out-of-band: operator obtains
-#    - agent-config-2.6.1.tgz                (from a separate channel)
-#    - agent-config-2.6.1.sha256             (separate-channel manifest, GPG-signed)
-#    - public.gpg                            (operator-supplied trust root)
-
-# 2. On the target machine:
-bash scripts/hermetic-install.sh \
-  --tarball ./agent-config-2.6.1.tgz \
-  --manifest ./agent-config-2.6.1.sha256 \
-  --gpg-key ./public.gpg
-```
-
-Outcomes recorded in `~/.event4u/agent-config/installed.lock`:
-
-```yaml
-schema_version: 1
-agent_config_version: "2.6.1"
-installation_mode: "hermetic"             # additive field (schema_v1 + extension)
-package_checksum: "sha256:<hex>"          # sha256 of the verified tarball
-signature_verified: true                  # GPG verification result
-installed_at: "2026-05-13T09:42:00Z"
-tools:
-  - claude
-```
-
-> **Platform support.** Unix-only (macOS + Linux). The script depends
-> on `bash`, `sha256sum`/`shasum`, and `gpg`. Windows support is
-> future scope per the Phase 2 council session (o1 verdict). Windows
-> users go through Path B (offline cache) on WSL.
-
-> **Schema cadence.** The three additional fields are written under
-> `schema_version: 1` as additive keys. The bump to
-> `schema_version: 2` is captured as a deferred ADR candidate in
-> `agents/roadmaps/road-to-distribution-maturity.md` Notes § "Phase 2
-> lock-schema extension — ADR candidate" — not opened this PR.
-
-## No-internet developer runbook
-
-A developer arrives on Monday with no network and finds a broken
-`npx` cache (corrupted, stale, or never staged). Recovery:
-
-1. **Confirm no-network.** `curl -m 5 https://registry.npmjs.org/ ||
-   echo "offline as expected"`.
-2. **Inventory what is local.**
-   - `ls ~/.npm/_cacache/` — is the offline cache present?
-   - `cat ~/.event4u/agent-config/installed.lock` — was a prior
-     install successful?
-3. **Pick a path:**
-   - Cache present + lock present → **Path B**, `npx --prefer-offline`.
-   - Cache present + lock missing → **Path B**, then `validate`.
-   - Cache missing + tarball + manifest present → **Path D**.
-   - Cache missing + nothing else → ask the IT contact to deliver
-     either a fresh tarball (for Path D) or a fresh cache archive
-     (for Path B). Do not attempt to bridge to the registry.
-4. **Verify.** After whichever path, run `npx --prefer-offline
-   @event4u/agent-config validate` and confirm exit code zero. If
-   `validate` fails on a checksum or version mismatch, the cache
-   or tarball is stale — re-acquire, do not edit `installed.lock`
-   by hand.
-
-> No code recovery path goes through editing `installed.lock`
-> manually. The file is atomic (`os.replace`) by design — hand-edits
-> bypass the schema invariant and will be overwritten on the next
-> `init`/`update`.
-
-## See also
-
-- `agents/roadmaps/road-to-distribution-maturity.md` § Phase 2 — the
-  roadmap entry that produced this document.
-- `agents/runtime/council/questions/composer-fallback-feasibility.md` — the
-  question that rejected the Composer path.
-- `agents/runtime/council/questions/hermetic-install-scaffolding.md` — the
-  question that shaped Path D.
-- `docs/decisions/ADR-007-agent-discovery-scopes.md` — the lock
-  manifest contract that Phase 2 extends additively.