From e89eb7295f63f29fd7f59850ef8110af43cbc33d Mon Sep 17 00:00:00 2001 From: Chris Phillipson Date: Fri, 24 Jul 2026 11:28:47 -0700 Subject: [PATCH] =?UTF-8?q?feat:=20machine-scoped=20guidance=20blocks=20go?= =?UTF-8?q?=20user-level=20=E2=80=94=20~/.codex/AGENTS.md=20target=20(ADR-?= =?UTF-8?q?0008)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The block registry knew two guidance targets: machine-wide ~/.claude/CLAUDE.md and the PROJECT AGENTS.md. That asymmetry meant (a) only synced repos ever got codex-side guidance, and (b) machine state leaked into git — the dual-mode block exists only when both hosts are enabled in kit.json, a fact about one machine, yet it was committed into shared checked-in AGENTS.md files. - New `agents-user` target → ~/.codex/AGENTS.md (codex's global guidance file). Dir-exists gated — ak never creates ~/.codex; one-time .bak before the first managed rewrite, mirroring CLAUDE.md's. - `ruflo-dual-mode-reference` re-scoped to ['claude','agents-user']; the project `agents` target stays for genuinely repo-scoped rows. - Migration: each target now also strips sentinel-present blocks that no longer list it (`retiredForTarget` forced-strip rows), so project AGENTS.md files carrying the old block heal on their next sync. - One shared `guidanceTargets()` helper replaces the duplicated target lists in sync.mjs/status.mjs. - Docs aligned with this and #47/#48: template sentinel comment, README setup/status/dual rows (truthful natives, memory-pin, pre-flight refusal), MAINTAINER.md registry description, UPGRADING/ TROUBLESHOOTING remedies. ADR-0008 records the scope split. 314 kit tests green (10 new); full check chain green. Live dry-run: CLAUDE.md upsert + project AGENTS.md strip + ~/.codex/AGENTS.md upsert. --- MAINTAINER.md | 2 +- README.md | 6 +- claude/dual-mode-reference.md | 11 +- docs/TROUBLESHOOTING.md | 2 + docs/UPGRADING.md | 5 +- docs/adr/0008-guidance-target-scope-split.md | 107 ++++++++++++++ docs/adr/README.md | 6 +- src/commands/status.mjs | 28 ++-- src/commands/sync.mjs | 25 ++-- src/lib/blocks.mjs | 48 ++++++- src/lib/paths.mjs | 7 + tests/kit/blocks-dual-mode.test.mjs | 2 +- tests/kit/guidance-targets.test.mjs | 143 +++++++++++++++++++ 13 files changed, 349 insertions(+), 43 deletions(-) create mode 100644 docs/adr/0008-guidance-target-scope-split.md create mode 100644 tests/kit/guidance-targets.test.mjs diff --git a/MAINTAINER.md b/MAINTAINER.md index 3368f1ba..92948b37 100644 --- a/MAINTAINER.md +++ b/MAINTAINER.md @@ -46,7 +46,7 @@ src/ sqlite.mjs # node:sqlite helpers (scalar, checkpoint, withDb) versions.mjs # installedVersion, driftReport, KIT_PKG ruvnet-brain.mjs # RuvNet Brain: on-disk detection + GitHub-release drift (NOT an npm pkg) - blocks.mjs # CLAUDE.md / AGENTS.md managed-block registry + syncBlocks + blocks.mjs # managed-block registry + syncBlocks + guidanceTargets (3 targets: ~/.claude/CLAUDE.md, project AGENTS.md, ~/.codex/AGENTS.md) hosts.mjs # host-adapter core: drivingHost() + HOST_ADAPTERS (guidance file, auth, statusline) providers.mjs # frontier-host + LLM-provider detect/wire (hosts, auth, MCP bridges, aqe router) routing.mjs # pure dual-host routing policy: defaults, projections, primary-host swap diff --git a/README.md b/README.md index 1a4da53c..fc04d3ff 100644 --- a/README.md +++ b/README.md @@ -66,12 +66,12 @@ What the verbs cover: | Verb | What it does | | ------ | -------------- | -| **setup** | Installs/updates ruflo + agentic-qe + the **agentdb** CLI globally (handling npm ≥11.17's `allow-scripts` so natives build; agentdb is pinned to ruflo's bundled version so the shared learning store stays coherent), installs the **RuvNet Brain** (an offline knowledge base over the rUv stack, powering the `search_ruvnet` MCP — a ~2 GB one-time download, prompted; skip with `--no-ruvnet-brain`), deploys the token-audit skill, merges the managed guidance blocks into `~/.claude/CLAUDE.md`, offers one-time MCP registration (user scope, with a tool-family picker), and — inside a repo — initializes the project: sanitized `ruflo init`, absolute memory-path pin, a **verified** store→disk write, statusline footer, and a background daemon with **local-only ($0) workers** (token-spending AI workers stay opt-in behind upstream's machine-wide budget). Project scope triggers on a `.git` directory in the current folder; without one it's skipped with a note. `--project` forces it anyway (e.g. a not-yet-`git init`-ed folder), `--minimal` skips it, `--yes` accepts all prompts (non-interactive), `--no-aqe` / `--no-ruvnet-brain` / `--no-security` disable those subsystems, and `--reconfigure` re-offers MCP registration. `--codex` enables + installs the Codex host during setup (dual-mode; both hosts then run at once), and `--primary-host claude\|codex` picks which host leads (codex implies `--codex`). | -| **status** | Per-subsystem ✓/⚠/✗ (versions, the kit's own version, **ruvnet-brain** (present + release drift, or "not installed"), natives, security, learning, aqe/RVF, **agentdb** (CLI present + coherent with ruflo's bundled version, or a store-skew warning), MCP, **hosts** (claude/codex — version + install method + **auth mode** (subscription $0 vs metered api-key), with the **primary** host marked and a *fail* when the primary host is absent), **providers** (host wiring + aqe fallback chain, or "drifted"/claude-only default), **routing** (per-activity Claude/Codex host+model policy, when dual-host — with drift vs the on-disk `agentOverrides`), daemons, CLAUDE.md blocks, statusline), each drift row naming what `sync` would do about it — plus a **health-history** line that flags regressions since the last sync (learning shrank, native slots dropped, drift/security backslid). | +| **setup** | Installs/updates ruflo + agentic-qe + the **agentdb** CLI globally (handling npm ≥11.17's `allow-scripts` so natives build; agentdb is pinned to ruflo's bundled version so the shared learning store stays coherent), installs the **RuvNet Brain** (an offline knowledge base over the rUv stack, powering the `search_ruvnet` MCP — a ~2 GB one-time download, prompted; skip with `--no-ruvnet-brain`), deploys the token-audit skill, merges the managed guidance blocks into the machine-wide guidance files (`~/.claude/CLAUDE.md`, plus `~/.codex/AGENTS.md` on codex machines), offers one-time MCP registration (user scope, with a tool-family picker), and — inside a repo — initializes the project: sanitized `ruflo init`, absolute memory-path pin, a **verified** store→disk write, statusline footer, and a background daemon with **local-only ($0) workers** (token-spending AI workers stay opt-in behind upstream's machine-wide budget). Project scope triggers on a `.git` directory in the current folder; without one it's skipped with a note. `--project` forces it anyway (e.g. a not-yet-`git init`-ed folder), `--minimal` skips it, `--yes` accepts all prompts (non-interactive), `--no-aqe` / `--no-ruvnet-brain` / `--no-security` disable those subsystems, and `--reconfigure` re-offers MCP registration. `--codex` enables + installs the Codex host during setup (dual-mode; both hosts then run at once), and `--primary-host claude\|codex` picks which host leads (codex implies `--codex`). | +| **status** | Per-subsystem ✓/⚠/✗ (versions, the kit's own version, **ruvnet-brain** (present + release drift, or "not installed"), natives (agentdb copies **and** ruflo's own memory runtime — the one `npx ruflo memory` loads — load-tested for a native better-sqlite3, not just the agentdb dirs), **memory-pin** (warns when `CLAUDE_FLOW_DB_PATH` points off the live DB), security, learning, aqe/RVF, **agentdb** (CLI present + coherent with ruflo's bundled version, or a store-skew warning), MCP, **hosts** (claude/codex — version + install method + **auth mode** (subscription $0 vs metered api-key), with the **primary** host marked and a *fail* when the primary host is absent), **providers** (host wiring + aqe fallback chain, or "drifted"/claude-only default), **routing** (per-activity Claude/Codex host+model policy, when dual-host — with drift vs the on-disk `agentOverrides`), daemons, guidance-file blocks (`~/.claude/CLAUDE.md`, project `AGENTS.md`, and `~/.codex/AGENTS.md` on codex machines), statusline), each drift row naming what `sync` would do about it — plus a **health-history** line that flags regressions since the last sync (learning shrank, native slots dropped, drift/security backslid). | | **sync** | The one convergence verb: upgrades first when a new release exists, then re-heals everything an upgrade wipes, then re-checks and reports. Included in that heal: it **installs any enabled frontier host** (claude/codex) that's entirely absent — never touching an external (mise/brew/native) install — and **re-applies provider wiring** (the `ENABLE_*` host env, the aqe fallback chain, and ruflo API providers) whenever it has drifted — and, on a dual-host project, **seeds/heals the per-activity routing policy** (materializing it into agentic-qe's `agentOverrides`, e.g. after an aqe upgrade first makes it eligible). It also **installs/repins the standalone `agentdb` CLI** to ruflo's bundled version (keeping the shared cognitive store coherent) and appends a **health-history snapshot** so `status` can flag regressions across syncs. It also **re-runs the RuvNet Brain installer** to pull the latest release when the on-disk KB has drifted (or installs it if absent, when enabled). It also **self-updates the kit**: when a newer `@pacphi/agentic-kit` exists it installs it as the *last* step (the new code applies from the next `ak` run, never mid-sync). Prerelease installs (`4.0.0-alpha.*`) track the `next` npm dist-tag as well as `latest`, so alphas see their successors; stable installs only ever follow `latest`. `--no-upgrade` skips the self-update along with the package upgrades. | | **dashboard** | Opens a read-only local web dashboard (`127.0.0.1:7431`, localhost-only, never detaches) that renders the same subsystem view as `ak status` in an Apple-style five-tab layout — **Overview · Hosts & Routing · Providers · Runtime · Intelligence** — with count badges on any tab holding a failing/warning subsystem. Problems never hide behind a tab: Overview aggregates every attention card, a quiet update notice, and a jump-to status map of all subsystems; Providers shows the **models in play** (distinct host+model pairs from your routing policy); Hosts & Routing carries the **per-activity routing matrix** (vendor-coded Claude/Codex host + model per activity) when dual-host routing is configured; Intelligence keeps the learning-over-time strip. Fully self-contained and offline (no external fetches, nothing leaves your machine). **Auto-opens your browser** (`--no-open` to just print the URL for headless/SSH); `--port N` to change the port; tabs deep-link (`#providers`) and persist. Stop with Ctrl-C. (Also available as `ak x dashboard`.) | | **admin** | Opens the **maintainer admin** (`127.0.0.1:7432`, localhost-only, foreground) — the project-telemetry sibling of `dashboard`: unique repo visitors and cloners (GitHub traffic API, needs a push-access token via `GITHUB_TOKEN`/`GH_TOKEN`/`gh auth token` — panels degrade honestly without one), npm download momentum (last 7d vs prior 7d, sparklines), release pulls, a **"since you last looked"** delta strip over a local baseline, open issues/PRs from others (oldest first), and external humans ranked by recency (bots excluded). Access is gated by a **per-session token** carried in the URL fragment and sent header-only; the page makes **zero external fetches** (the server proxies GitHub/npm; your credential never reaches the page or the payload — ADR-0007). Where `dashboard` is offline-first, `admin` does deliberate GitHub/npm egress — that contract split is why they're siblings, not tabs. `--port N`, `--no-open`; Ctrl-C stops. (Also available as `ak x admin`.) | -| **dual** | Runs a **Claude + Codex collaboration swarm** using your per-activity routing policy: `ak dual run