@event4u/agent-config 2.6.0 → 2.7.0

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

@@ -0,0 +1,201 @@
+# 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/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/council-questions/composer-fallback-feasibility.md` — the
+  question that rejected the Composer path.
+- `agents/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.

package/docs/setup/per-ide/augment.md

@@ -1,10 +1,18 @@
 # Augment Code Setup
 
-Augment Code is the **substrate** for this package — every other tool
-mirrors content from the canonical `.augment/` tree. The Augment
-extension (VS Code, JetBrains) reads `.augment/rules/`,
-`.augment/skills/`, `.augment/commands/`, `.augment/personas/`, and
-`.augment/contexts/` directly.
+Augment Code is **global-only** in this package — content ships from a
+single user-scope tree at `~/.augment/` and the Augment extension
+(VS Code, JetBrains) reads it on every workspace. Per-project
+`.augment/` content is not installed; project `init` writes only the
+`.augment/settings.json` marker that authorizes the plugin for the
+workspace.
+
+> **Why global-only?** Augment counts the full body of every file in
+> `.augment/rules/` against its 49,512-char workspace-guidelines limit.
+> The package-wide rule set exceeds that limit on every workspace, so
+> a single user-scope install is the canonical surface and the
+> overflow is a known, accepted trade-off. See
+> [`ADR-007 § Amendment 2026-05-13 — global-only`](../../decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only).
 
 ## Prerequisites
 
@@ -13,28 +21,31 @@ extension (VS Code, JetBrains) reads `.augment/rules/`,
 
 ## Install
 
-Project scope (default):
+Global scope (the only supported path — deploys the full bundle to
+`~/.augment/`):
 
 ```bash
-npx @event4u/agent-config init --tools=augment
+npx @event4u/agent-config init --tools=augment --global
 ```
 
-Global scope (cross-project, deploys the full bundle to `~/.augment/`):
+`--tools=augment` without `--global` is rejected with a directive
+error; `--tools=all` (project scope) silently filters `augment` out.
 
-```bash
-npx @event4u/agent-config init --tools=augment --global
-```
+Populates (`~/.augment/`):
+
+- `~/.augment/rules/`     — kernel (9 Iron-Law rules) + tier-1/2 routed rules
+- `~/.augment/skills/`    — domain skills
+- `~/.augment/commands/`  — slash commands
+- `~/.augment/personas/`  — review-lens personas
+- `~/.augment/contexts/`  — knowledge-layer contexts
+- `~/.augment/templates/` — scaffolds for AGENTS.md, copilot-instructions, etc.
 
-Populates (project):
+A project-scope `init` (any `--tools=…` selection except `augment`)
+still writes:
 
-- `.augment/rules/`     — kernel (9 Iron-Law rules) + tier-1/2 routed rules
-- `.augment/skills/`    — domain skills
-- `.augment/commands/`  — slash commands
-- `.augment/personas/`  — review-lens personas
-- `.augment/contexts/`  — knowledge-layer contexts
-- `.augment/templates/` — scaffolds for AGENTS.md, copilot-instructions, etc.
-- `AGENTS.md`           — canonical agent self-orientation
-- `.agent-settings.yml` — per-project knobs
+- `.augment/settings.json` — plugin activation marker for the workspace
+- `AGENTS.md`              — canonical agent self-orientation
+- `.agent-settings.yml`    — per-project knobs
 
 ## How to use
 
@@ -53,9 +64,9 @@ Populates (project):
 ## Verification
 
 ```bash
-test -d .augment/rules
-test -d .augment/skills
-test -d .augment/commands
+test -d ~/.augment/rules
+test -d ~/.augment/skills
+test -d ~/.augment/commands
 test -f AGENTS.md
 ```
 
@@ -67,8 +78,9 @@ should cite the AGENTS.md emergency triage block.
 | Symptom | Fix |
 |---|---|
 | Skills not surfaced | Reload the Augment workspace; skills are indexed on session start. |
-| Symlinked sub-dirs missing | `.augment/skills` is a symlink to `.agent-src/skills`; run `task sync` to rebuild. |
-| Iron Laws not firing | Confirm `.augment/rules/` contains 9 kernel files (`task ci` validates the kernel count). |
+| `~/.augment/rules/` missing | Re-run `npx @event4u/agent-config init --tools=augment --global`. |
+| Workspace-guidelines overflow warning | Expected — the package rule set exceeds Augment's 49,512-char budget. See [`ADR-007 § Amendment 2026-05-13`](../../decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only). |
+| Iron Laws not firing | Confirm `~/.augment/rules/` contains 9 kernel files. |
 
 ## Cross-references
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.6.0",
+    "version": "2.7.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_bootstrap_tier_frontmatter.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""One-shot bootstrap — inject `tier: N` frontmatter into every slash command.
+
+Per Phase 4 Step 3 of `agents/roadmaps/road-to-distribution-maturity.md`.
+
+Walks `.agent-src.uncompressed/commands/**.md`. For each file:
+
+- Tier-0 promotions match TIER_0 below — typed by hand.
+- Tier-1 promotions match TIER_1 below — typed by hand.
+- Everything else defaults to **Tier-2** (per the contract).
+
+Idempotent — re-running is a no-op once tiers are tagged. The lint
+script `scripts/lint_command_tiers.py` enforces drift from here on.
+
+Run from repo root: `python3 scripts/_bootstrap_tier_frontmatter.py`.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+COMMANDS_DIRS = (
+    REPO_ROOT / ".agent-src.uncompressed" / "commands",
+    REPO_ROOT / ".agent-src" / "commands",
+)
+
+# Tier-0 — daily-driver slash commands (per docs/contracts/command-surface-tiers.md).
+# Paths are relative to COMMANDS_DIR.
+TIER_0 = {
+    "onboard.md",
+    "commit.md",
+    "work.md",
+    "implement-ticket.md",
+    "agent-status.md",
+    "agent-handoff.md",
+}
+
+# Tier-1 — power-user / maintainer / orchestrator slash commands.
+TIER_1 = {
+    "create-pr.md",
+    "review-changes.md",
+    "optimize.md",
+    "roadmap.md",
+    "feature.md",
+    "fix.md",
+    "judge.md",
+    "memory.md",
+    "council.md",
+    "agents.md",
+    "commit/in-chunks.md",
+    "create-pr/description-only.md",
+    "quality-fix.md",
+    "prepare-for-review.md",
+    "estimate-ticket.md",
+    "refine-ticket.md",
+    "bug-fix.md",
+    "bug-investigate.md",
+    "jira-ticket.md",
+    "compress.md",
+    "mode.md",
+    "project-analyze.md",
+    "project-health.md",
+    "rule-compliance-audit.md",
+    "threat-model.md",
+    "set-cost-profile.md",
+    "sync-agent-settings.md",
+    "sync-gitignore.md",
+    "upstream-contribute.md",
+}
+
+FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+
+
+def classify(rel_path: str) -> int:
+    if rel_path in TIER_0:
+        return 0
+    if rel_path in TIER_1:
+        return 1
+    return 2
+
+
+def inject_tier(text: str, tier: int) -> tuple[str, bool]:
+    """Inject `tier: N` into the frontmatter block. Returns (new_text, changed).
+
+    If frontmatter already contains `tier:`, the existing value wins
+    (idempotent — bootstrap never overrides a manual tag).
+    """
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return text, False
+    block = m.group(1)
+    if re.search(r"^tier:\s*[012]\s*$", block, re.MULTILINE):
+        return text, False
+    # Insert `tier: N` right after the `name:` line if present, else at
+    # the top of the block.
+    name_match = re.search(r"^(name:\s*\S+)$", block, re.MULTILINE)
+    if name_match:
+        new_block = (
+            block[: name_match.end()]
+            + f"\ntier: {tier}"
+            + block[name_match.end() :]
+        )
+    else:
+        new_block = f"tier: {tier}\n{block}"
+    new_fm = f"---\n{new_block}\n---\n"
+    return new_fm + text[m.end() :], True
+
+
+def main() -> int:
+    overall_tagged = 0
+    overall_skipped = 0
+    for commands_dir in COMMANDS_DIRS:
+        if not commands_dir.is_dir():
+            print(f"[bootstrap-tier] no commands dir: {commands_dir}")
+            continue
+        files = sorted(commands_dir.rglob("*.md"))
+        tagged = 0
+        skipped = 0
+        by_tier = {0: 0, 1: 0, 2: 0}
+        for path in files:
+            rel = path.relative_to(commands_dir).as_posix()
+            # Sub-AGENTS.md files are not slash commands.
+            if rel.endswith("AGENTS.md"):
+                continue
+            tier = classify(rel)
+            by_tier[tier] += 1
+            text = path.read_text(encoding="utf-8")
+            new_text, changed = inject_tier(text, tier)
+            if changed:
+                path.write_text(new_text, encoding="utf-8")
+                tagged += 1
+            else:
+                skipped += 1
+        overall_tagged += tagged
+        overall_skipped += skipped
+        rel_label = commands_dir.relative_to(REPO_ROOT)
+        print(
+            f"[bootstrap-tier] dir={rel_label} tagged={tagged} "
+            f"skipped={skipped} tier-0={by_tier[0]} "
+            f"tier-1={by_tier[1]} tier-2={by_tier[2]}"
+        )
+    print(
+        f"[bootstrap-tier] total: tagged={overall_tagged} "
+        f"skipped={overall_skipped}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())