@adia-ai/adia-ui-forge 0.1.3 → 0.8.0

package/skills/adia-ui-ops/references/audit-patterns/browser-bundle-node-imports.md

@@ -1,154 +0,0 @@
----
-name: browser-bundle-node-imports
-applies-to: monorepos with shared packages reachable from both Node and browser bundles
-severity: hard-runtime-regression (silent in tests)
-detected: 2026-05-12 (chat-ui v0.4.7 §72 follow-up)
-related-postmortem: chat-ui/.brain/postmortems/2026-05-12-browser-bundle-node-imports.md
----
-
-# Audit pattern — Browser bundle crashes from top-level `import 'node:*'`
-
-## The bug class
-
-A module that needs to work in both Node (server-side smoke, tests, MCP, evals) and the browser (live app surface) statically imports `node:fs`, `node:path`, `node:url`, `node:crypto`, etc. at module top level. The module is reachable from the browser bundle via static import chain.
-
-In the browser, Vite (or any bundler) externalizes the `node:*` modules — it can't bundle them. Vite emits a shim that throws on **property access**, not on import resolution. So:
-
-1. Bundler logs a warning: `Module "node:path" has been externalized for browser compatibility.`
-2. Module's top-level code accesses a property (`path.dirname(...)`, `fs.existsSync(...)`).
-3. Module init throws.
-4. First consumer up the import chain fails to mount.
-5. User sees either a hard error or a graceful-degradation message ("demo mode", "fallback enabled", etc.) depending on the import site's catch handling.
-
-## Why it's hard to catch
-
-- **Vitest is Node-only.** Tests pass.
-- **The bundler doesn't fail-fast.** It externalizes and warns; the bug surfaces only when production code accesses the externalized stub.
-- **`@vite-ignore` on inner dynamic imports is a known defensive pattern** but doesn't help here — the failure is at top-level static import, before any runtime branch.
-- **Sibling modules may already be correctly dual-mode'd.** The pattern is well-known; one module gets fixed; the next sibling slips through.
-- **No CI gate detects this.** A `vite build` smoke would catch it, but most repos run `vitest` + `npm test` and call it done.
-
-## The discriminating signal
-
-Top-level static `import .* 'node:*'` in a module reachable from the browser bundle. Distinct from:
-
-```js
-// SAFE — dynamic, Node-only branch
-if (IS_NODE) {
-  const fs = await import(/* @vite-ignore */ 'node:fs');
-}
-```
-
-vs.
-
-```js
-// UNSAFE — runs at module init regardless of environment
-import fs from 'node:fs';
-const __dirname = fs.existsSync(...);  // throws in browser
-```
-
-## How to audit
-
-```bash
-# Find every browser-reachable module with top-level static node:* imports
-grep -rln "^import .* 'node:" packages/ apps/ playgrounds/ catalog/ 2>/dev/null \
-  | grep -v 'node_modules\|dist/\|/test/\|\.test\.\|/evals/\|/scripts/\|server\.js'
-```
-
-Each hit is a candidate. Triage:
-
-1. **Node-only file (`.mjs` extension + imports `playwright`/`fs`/etc. liberally)** → safe, ignore.
-2. **Used only by Node-only consumers (MCP scripts, evals, tests)** → safe.
-3. **Imported by anything in `core/`, `strategies/monolithic/`, `strategies/zettel/` (if lazy-loaded) — trace upward.** If the chain reaches `apps/*/app/*.contents.js` or a similar browser entry, it's a bug.
-4. **Lazy-loaded via `await import('./this-module.js')`** → safe (the static-import trap doesn't fire).
-
-Look for protective comments in registries / barrels: e.g.,
-
-```js
-// Zettel is lazy-loaded — it transitively imports node:fs / node:path / node:url.
-// Static-importing it here would break browser loads of core/generator.js.
-```
-
-That comment is the canonical protective documentation — when you see it, the lazy-load wall is intentional. Check that the wall hasn't been breached by a sibling `import` statement at the top of another file in the same package.
-
-## The fix pattern
-
-Replace top-level static `import 'node:*'` with the dual-mode loader:
-
-```js
-const IS_NODE =
-  typeof process !== 'undefined' &&
-  typeof process.versions?.node === 'string';
-
-// Vite resolves this at build time; at runtime in Node the variable is unused.
-let _globModules = null;
-if (!IS_NODE) {
-  try {
-    _globModules = import.meta.glob('../path/to/files/**/*.json', {
-      query: '?raw',
-      import: 'default',
-      eager: false,
-    });
-  } catch {
-    // Not in a Vite context — no data in this realm.
-  }
-}
-
-async function _loadNode() {
-  const fs = await import(/* @vite-ignore */ 'node:fs');
-  const path = await import(/* @vite-ignore */ 'node:path');
-  // ... Node-only logic
-}
-
-async function _loadBrowser() {
-  if (!_globModules) return;
-  for (const [, loader] of Object.entries(_globModules)) {
-    const raw = await loader();
-    // ... browser-only logic
-  }
-}
-
-export async function load() {
-  if (IS_NODE) await _loadNode();
-  else await _loadBrowser();
-}
-
-// Eager top-level load: Node side awaits; browser side fires-and-forgets
-// (because module-init top-level await is permitted but blocks all importers).
-if (IS_NODE) {
-  await load();
-} else {
-  load().catch(() => {});
-}
-```
-
-The `import.meta.glob(...)` pattern is Vite-specific. For non-Vite bundlers, swap in the bundler's equivalent or expose a `setLoader(fn)` hook.
-
-## Trip-wires (what to add)
-
-1. **Pre-cut audit**: run the grep above as part of the release F-N1 dry-run. Hit count == 0 for browser-reachable surface, OR every hit traces to a Node-only-consumer chain.
-
-2. **Static-source audit** — shipped as `scripts/release/check-browser-safe.mjs` (§83, v0.4.8). Walks `packages/*` for `*.js` / `*.mjs`, filters out Node-only directories via `NODE_ONLY_PATTERNS`, and greps for top-level `import ... from 'node:*'` statements. Exits 0 on clean tree; `--strict` exits 1 on findings. Wired into `npm run check` composite + the lockstep-release skill's pre-cut step. Faster than a vite-build approach (~1s on 536 files vs ~minute per app); the build-based companion is deferred until the static check proves insufficient.
-
-3. **Playwright end-to-end probe**: extend any existing smoke spec (e.g. `smoke:genui-error-ux`) to assert specific behavior that requires the browser-side composition library / catalog to be loaded (e.g. retrieval strategy is reported, not just "demo mode"). Catches the symptom even if the trip-wire grep misses an instance.
-
-## Common patterns this catches
-
-- Loaders that walk a corpus directory at module init (`fs.readdirSync` → `Map` of records)
-- Cache files that hash + write fingerprints (`crypto.createHash` + `fs.writeFile`)
-- Issue reporters that write `.brain/findings/` JSONL files (`fs.appendFile`)
-- Path resolvers that compute `__dirname` from `import.meta.url`
-
-In each case, the Node use case is real, but it must be guarded.
-
-## What this audit does NOT catch
-
-- Runtime calls to `process.env.SOMETHING` (those are separate; Vite injects polyfills) — those need `typeof process !== 'undefined'` guards but the failure mode is different.
-- `Buffer` references (browser polyfill is fragmented; see Vite docs).
-- Worker / service-worker boundaries (`new Worker(new URL(...))`) — those need their own audit.
-
-## Reference incident
-
-chat-ui v0.4.7 §72 follow-up — `packages/a2ui/compose/strategies/zettel/composition-library.js` had top-level `import 'node:fs/path/url'` from the v0.4.4 §38 fragment-library → composition-library rename. Reached the browser via `gen-ui.contents.js → @adia-ai/a2ui-compose → core/reference.js → strategies/zettel/composition-library.js`. Fixed in commit `76dbcff2`. Postmortem: `/Users/kimba/Projects/adia/gen-ui-kit/.brain/postmortems/2026-05-12-browser-bundle-node-imports.md`. Latent for ~8 days. Detected by user runtime, not CI.
-
-Sibling module `retrieval/component-catalog.js` had the same risk but was correctly dual-mode'd in an earlier arc. The pattern was known; the fix was not propagated. **The audit gap was: no one ran the discriminating grep across the package after fixing the first module.**

package/skills/adia-ui-ops/references/audit-patterns/changelog-unreleased-bloat.md

@@ -1,75 +0,0 @@
-# `[Unreleased]` block bloat detection
-
-**Added:** 2026-05-02 after the AdiaUI repo's root `CHANGELOG.md`
-accumulated 933 lines of stale-promoted content that already existed
-in dated entries above.
-
-## The drift class
-
-Each release cut authors a new dated entry (`## [YYYY-MM-DD — …]`)
-but doesn't wipe the `[Unreleased]` content that was just promoted.
-Over weeks, `[Unreleased]` accumulates content that's already shipped.
-
-Effects:
-- File size bloats (root CHANGELOG was 3118 → 2202 lines after wipe).
-- New readers can't tell what's actually pending — the long block
-  looks like a backlog about to ship.
-- `[Unreleased]` becomes a duplicate-content hazard for grep ("was
-  this fixed?" → it appears in 3 places).
-
-## Detection
-
-```bash
-# Count lines per package's [Unreleased] block
-for f in CHANGELOG.md packages/**/CHANGELOG.md; do
-  unreleased_lines=$(awk '/^## \[Unreleased\]/,/^## \[/' "$f" 2>/dev/null | wc -l)
-  echo "$f: $unreleased_lines lines"
-done | sort -t: -k2 -n -r
-```
-
-**Threshold:** > 30 lines is a smell. Likely duplicates the dated
-entry below. The actual content of `[Unreleased]` should be:
-
-- Short (1-3 lines) summary of pending work for the next cut, OR
-- `_No pending changes._` when nothing is staged
-
-## Fix recipe
-
-1. Read the next dated entry below `[Unreleased]`.
-2. For each item in `[Unreleased]`, check if it's covered in the
-   dated entry. If yes, delete from `[Unreleased]`. If no, the
-   content is genuinely pending — leave it (or move to a more
-   accurate dated entry if it shipped earlier).
-3. Verify: line count drops; `git diff` shows only the wipe.
-
-Python helper for the bulk wipe (when `[Unreleased]` is fully
-duplicate content):
-
-```python
-import pathlib
-p = pathlib.Path("CHANGELOG.md")
-text = p.read_text()
-lines = text.splitlines()
-ur_start = next(i for i, l in enumerate(lines) if l.startswith("## [Unreleased]"))
-next_section = next(i for i in range(ur_start+1, len(lines)) if lines[i].startswith("## [2026-"))
-sep_idx = next(i for i in range(next_section-1, ur_start, -1) if lines[i].startswith("---"))
-
-replacement = ["## [Unreleased]", "", "_No pending changes._", ""]
-new_lines = lines[:ur_start] + replacement + lines[sep_idx:]
-p.write_text("\n".join(new_lines) + "\n")
-```
-
-## Prevention
-
-After every release cut:
-1. Wipe the released-package `[Unreleased]` to `_No pending changes._`
-   OR a 1-3 line summary of what's staged for the next cut.
-2. Wipe the root CHANGELOG `[Unreleased]` (if applicable).
-3. Verify: `wc -l <changelog>` is consistent with prior cuts.
-
-This is item #5 of the lockstep-release post-publish admin checklist.
-
-## Related
-
-- See [`feedback_changelog_unreleased_drift.md`](`~/.claude/projects/<repo>/memory/`) — the user-memory entry capturing this lesson.
-- `stale-audit` skill — runs this check as part of its 7-check sweep.

package/skills/adia-ui-ops/references/audit-patterns/coverage-gaps.md

@@ -1,187 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - entry-file-coverage.md
-  - redundancy-detection.md
-  - token-waste-detection.md
-  - staleness-tooling.md
-  - ../doc-types/adr-pattern.md
-  - ../doc-types/postmortem-pattern.md
-  - ../recipes/self-healing-hooks.md
-  - ../recipes/continuous-learning-loop.md
-primary_sources:
-  - https://agents.md — AGENTS.md canonical spec (AAIF / Linux Foundation, Aug 2025)
-  - https://adr.github.io/ — Architectural Decision Records
-  - https://github.com/joelparkerhenderson/architecture-decision-record
-  - https://sre.google/sre-book/postmortem-culture/ — Google SRE Book, postmortem culture
-  - https://increment.com/on-call/whats-the-incident/ — Incident response patterns
-status: research-verified
----
-
-# Coverage gaps (delivers Promise 1, "less-wasteful" + Promise 5, "continuously-learning")
-
-> **The premise.** A repo without an AGENTS.md is invisible to multi-tool agents; a repo without ADRs has no memory of why anything is the way it is; a repo without postmortems is condemned to relearn the same outage. This audit catches the *missing* canonical files — not the bloated ones, not the stale ones, the ones that aren't there at all.
-
-## Why this is Promise 1 + Promise 5
-
-| Promise | Why missing canonicals violate it |
-|---|---|
-| **1. Less-wasteful** | An agent that can't find AGENTS.md re-derives conventions every session. A missing CHANGELOG forces every agent into `git log` archaeology. |
-| **5. Continuously-learning** | Without ADRs, decisions evaporate after PRs merge. Without postmortems, the org relearns the same outage. |
-
-Sibling `entry-file-coverage.md` checks that AGENTS.md/CLAUDE.md/.cursorrules are well-formed. *This* pattern checks the broader canonical set.
-
-## The expected canonical set
-
-| Tier | Path | Severity if missing | Why |
-|---|---|---|---|
-| **Required** | `AGENTS.md` | Critical | Multi-tool entry point; without it, no agent knows the repo |
-| **Required** | `CLAUDE.md` (or symlink → `AGENTS.md`) | Critical | Claude Code does not read AGENTS.md natively (issue #31005) |
-| **Required** | `README.md` | High | Human + LLM landing; GitHub renders it; first thing every search hits |
-| **Required** | `CHANGELOG.md` | High | Append-only history; without it, "what changed" is git-archaeology |
-| **Required** | `.brain/adrs/` | Medium | Decision memory; promise 5 home |
-| **Conditional** | `.brain/postmortems/` | Medium *if production-facing* | Incident memory; only meaningful if the repo deploys |
-| **Recommended** | `ARCHITECTURE.md` | Low | Big-picture reference (matklad pattern, repo root); substitutable with well-organized ADRs |
-| **Recommended** | `PLAN.md` | Low | Forward-looking roadmap; substitutable with issues |
-| **Recommended** | `.brain/runbooks/` | Low *if production-facing* | Operational memory; on-call counterpart to postmortems |
-| **Recommended** | `CONTRIBUTING.md` | Low | Contributor guide; collapsible into AGENTS.md |
-| **Recommended** | `SECURITY.md` | Low | Vuln-disclosure pointer; GitHub surfaces it natively |
-
-The conditional tier triggers on the production-facing heuristic below. The recommended tier is advisory — emit a finding, don't fail the audit.
-
-## The production-facing heuristic
-
-Postmortems and runbooks only matter if the repo runs in production. The audit infers production-facing from any of:
-
-| Signal | What it says |
-|---|---|
-| `Dockerfile` (or `Containerfile`) | Builds a container — likely deployable |
-| `.github/workflows/*deploy*.yml` (or `*release*.yml`, `*publish*.yml`) | CI deploys this |
-| `kubernetes/`, `k8s/`, `helm/`, `charts/` | Deploys to k8s |
-| `terraform/`, `*.tf`, `pulumi/`, `cdk.json` | Manages live infrastructure |
-| `fly.toml`, `vercel.json`, `netlify.toml`, `render.yaml`, `railway.json`, `app.yaml` | Deploys to a PaaS |
-| `serverless.yml`, `sam.yaml`, `template.yaml` | Deploys serverless |
-
-Any one signal flips the conditional tier on. Library-only repos skip postmortems and runbooks — but still get ADRs.
-
-## Detection logic
-
-```bash
-#!/usr/bin/env bash
-# coverage-gaps.sh — emit findings for missing canonical docs
-set -euo pipefail
-
-emit() {
-  # severity, path, message
-  printf 'COVERAGE-GAP\t%s\t%s\t%s\n' "$1" "$2" "$3"
-}
-
-# 1. Required tier — always checked
-[ -f AGENTS.md ] || emit critical AGENTS.md \
-  "No AGENTS.md at repo root. Multi-tool agents have no entry point."
-
-if [ ! -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
-  emit critical CLAUDE.md \
-    "No CLAUDE.md (Claude Code does not read AGENTS.md natively as of Apr 2026). Symlink or thin pointer required."
-fi
-
-[ -f README.md ] || emit high README.md \
-  "No README.md at repo root. Human and LLM landing surface missing."
-
-[ -f CHANGELOG.md ] || emit high CHANGELOG.md \
-  "No CHANGELOG.md. 'What changed lately' becomes git-archaeology for every agent."
-
-[ -d .brain/adrs ] || [ -d docs/adrs ] || [ -d docs/adr ] || [ -d docs/decisions ] || emit medium .brain/adrs/ \
-  "No ADR directory. Decision memory will evaporate after PRs merge. (Promise 5)"
-
-# 2. Conditional tier — production-facing check
-production=false
-for signal in Dockerfile Containerfile fly.toml vercel.json netlify.toml \
-              render.yaml railway.json app.yaml serverless.yml sam.yaml \
-              template.yaml docker-compose.prod.yml cdk.json pulumi.yaml; do
-  [ -e "$signal" ] && production=true && break
-done
-[ "$production" = false ] && compgen -G ".github/workflows/*deploy*"  >/dev/null 2>&1 && production=true
-[ "$production" = false ] && compgen -G ".github/workflows/*release*" >/dev/null 2>&1 && production=true
-[ "$production" = false ] && compgen -G ".github/workflows/*publish*" >/dev/null 2>&1 && production=true
-[ "$production" = false ] && [ -d kubernetes ] && production=true
-[ "$production" = false ] && [ -d k8s ]        && production=true
-[ "$production" = false ] && [ -d helm ]       && production=true
-[ "$production" = false ] && [ -d terraform ]  && production=true
-[ "$production" = false ] && compgen -G "*.tf" >/dev/null 2>&1 && production=true
-
-if [ "$production" = true ]; then
-  [ -d .brain/postmortems ] || [ -d docs/postmortems ] || [ -d docs/incidents ] || emit medium .brain/postmortems/ \
-    "Production-facing repo (deploy artifacts detected) but no postmortems directory. Incident memory will be lost. (Promise 5)"
-  [ -d .brain/runbooks ] || [ -d docs/runbooks ] || [ -d docs/operations ] || emit low .brain/runbooks/ \
-    "Production-facing repo but no runbooks directory. On-call response memory missing."
-fi
-
-# 3. Recommended tier — advisory only
-[ -f ARCHITECTURE.md ] || emit low ARCHITECTURE.md \
-  "No ARCHITECTURE.md. Big-picture reference missing (matklad pattern, repo root; substitutable with ADR set)."
-[ -f PLAN.md ] || emit low PLAN.md \
-  "No PLAN.md. Forward-looking roadmap missing (substitutable with issues)."
-[ -f CONTRIBUTING.md ] || emit low CONTRIBUTING.md \
-  "No CONTRIBUTING.md. Contributor guide can be collapsed into AGENTS.md for small repos."
-[ -f SECURITY.md ] || emit low SECURITY.md \
-  "No SECURITY.md. Vulnerability-disclosure pointer missing."
-```
-
-The output is one tab-separated finding per line, ready to fold into the audit report. The full hook lives in `../recipes/self-healing-hooks.md`.
-
-## Output shape (the gap-report row)
-
-```markdown
-- **MISSING — `.brain/postmortems/`** (severity: medium)
-  - Production-facing: `Dockerfile`, `.github/workflows/deploy.yml`, `terraform/` present.
-  - **Promise impact:** Promise 5 — the repo will relearn the same outage.
-  - **Recommendation:** create `.brain/postmortems/` from `../doc-types/postmortem-pattern.md`; backfill one recent incident.
-
-- **MISSING — `CHANGELOG.md`** (severity: high)
-  - **Promise impact:** Promise 1 — every agent re-derives "what changed lately" from `git log`.
-  - **Recommendation:** Keep-a-Changelog format; seed with `## [Unreleased]` if history is unrecoverable.
-```
-
-## Substitution rules (when "missing" is actually OK)
-
-The audit is opinionated, not pedantic. Three substitutions are accepted:
-
-| Expected | Acceptable substitute | Why |
-|---|---|---|
-| `.brain/adrs/` | `docs/decisions/` or `docs/adr/` (legacy) | Naming variant; same content shape |
-| `.brain/postmortems/` | `docs/incidents/` (legacy) | Naming variant |
-| `ARCHITECTURE.md` | Populated `.brain/adrs/` of 5+ entries | ADRs collectively *are* the architecture story |
-
-## What this pattern is NOT for
-
-- **Content quality** — coverage-gaps checks *presence*. `format-hygiene.md` and `stale-content.md` catch quality.
-- **Bloated files** — `token-waste-detection.md` handles oversize.
-- **Drift between two existing files** — `redundancy-detection.md` handles drift.
-- **Orphans** — `orphan-detection.md` (sibling, Promise 1).
-
-## Severity rubric (consolidated)
-
-| Finding | Severity | Promise impacted |
-|---|---|---|
-| AGENTS.md missing | Critical | 1 |
-| CLAUDE.md missing (no symlink) | Critical | 1 |
-| README.md missing | High | 1 |
-| CHANGELOG.md missing | High | 1, 5 |
-| `.brain/adrs/` missing | Medium | 5 |
-| `.brain/postmortems/` missing (production-facing) | Medium | 5 |
-| `.brain/runbooks/` missing (production-facing) | Low | 5 |
-| `ARCHITECTURE.md` missing | Low | 1 |
-| `CONTRIBUTING.md`, `SECURITY.md`, `PLAN.md` | Low | advisory |
-
-## Cross-references
-
-- Entry-file shape (sibling audit, AGENTS.md/CLAUDE.md form): `entry-file-coverage.md`
-- Format hygiene (does each canonical have the right shape?): `format-hygiene.md`
-- Redundancy between existing canonicals: `redundancy-detection.md`
-- Stale content within existing canonicals: `staleness-tooling.md`, `stale-content.md`
-- ADR shape: `../doc-types/adr-pattern.md`
-- Postmortem shape: `../doc-types/postmortem-pattern.md`
-- Self-healing hook (where these checks run on commit): `../recipes/self-healing-hooks.md`
-- Continuous learning loop (Promise 5 home): `../recipes/continuous-learning-loop.md`

package/skills/adia-ui-ops/references/audit-patterns/entry-file-coverage.md

@@ -1,122 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - pointer-validation.md
-  - orphan-detection.md
-  - ../standards/cross-tool-matrix.md
-primary_sources:
-  - https://agents.md — AGENTS.md canonical spec
-  - https://github.com/anthropics/claude-code/issues/31005 — Claude Code AGENTS.md request (open Apr 2026)
-  - https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/
-  - https://cursor.com/docs/rules — Cursor rules format
-  - https://docs.continue.dev/customize/deep-dives/rules
-status: research-verified
----
-
-# Audit pattern: entry-file coverage
-
-> **The first audit pass.** Before checking pointers, freshness, or orphans, verify that the right entry files exist and are well-formed.
-
-## What this pattern checks
-
-| # | Check | Pass criterion |
-|---|---|---|
-| 1 | `AGENTS.md` exists at repo root | Yes |
-| 2 | `AGENTS.md` has a "Where to find things" section | Yes — non-trivial section listing doc subfolders |
-| 3 | `AGENTS.md` has a "Memory primitives" section | Yes — points to ADRs, decisions, traces |
-| 4 | `AGENTS.md` has a `_Last reviewed:_` line or YAML `date:` | Yes |
-| 5 | If `CLAUDE.md` exists, it's a thin pointer (≤15 lines, references AGENTS.md) | Yes |
-| 6 | If `.cursor/rules` or `.cursorrules` exists, it's a thin pointer | Yes |
-| 7 | If `.windsurfrules` exists, it's a thin pointer | Yes |
-| 8 | If `.aider.conf.yml`, `.continue/`, etc., exist — examined for drift | Yes |
-| 9 | If `README.md` exists, it links to AGENTS.md (or AGENTS.md links from it) | Yes |
-| 10 | No two entry files contain conflicting content (drift detection) | Yes |
-
-## Files to enumerate
-
-The following should be examined as candidate entry files for LLM coding agents:
-
-| Path | Tool / convention | Reads AGENTS.md natively? |
-|---|---|---|
-| `AGENTS.md` | The canonical multi-tool standard (AAIF/Linux Foundation, Aug 2025) | n/a |
-| `CLAUDE.md` | Anthropic Claude Code | **No** (issue #31005) |
-| `~/.claude/CLAUDE.md` | Claude Code user-global; `CLAUDE.local.md` for personal overrides | **No** |
-| `.cursorrules` | Cursor (deprecated, still works) | Yes, also reads AGENTS.md |
-| `.cursor/rules/*.mdc` | Cursor (current) | Yes, also reads AGENTS.md |
-| `.windsurfrules`, `.windsurf/rules/` | Windsurf (Cognition since Dec 2025) | Yes |
-| `.aider.conf.yml` + `CONVENTIONS.md` | Aider | Configurable (not auto) |
-| `.continue/rules/*.md` | Continue.dev | **Not yet** (issue #6716) |
-| `.github/copilot-instructions.md`, `.github/instructions/**/*.instructions.md` | GitHub Copilot | Yes (added 2025-08-28); also reads CLAUDE.md, GEMINI.md |
-| `README.md` | Human + LLM landing | n/a |
-| `CONTRIBUTING.md` | Contributor guide (often agent-relevant) | n/a |
-| `GEMINI.md` | Google Gemini CLI / Jules | Yes — primary |
-| `~/.codex/AGENTS.md`, `AGENTS.override.md` | OpenAI Codex (user-global, override) | Yes — primary |
-
-> **Not in this matrix:** `HERMES.md` doesn't exist as a convention (NousResearch's Hermes Agent uses `~/.hermes/skills/`, not a project file). `GAS_TOWN.md` doesn't exist either (Gas Town is Steve Yegge's multi-agent orchestrator, not an agent). See `../standards/cross-tool-matrix.md`.
-
-Some of these may not apply to a given repo; that's fine. The audit checks them and reports presence/absence.
-
-## How to run the check (procedural)
-
-```text
-1. List files at repo root with names matching the entry-file table above.
-2. For each found file:
-   a. Get size, last-modified date.
-   b. Read content.
-   c. Classify: "fat" (>15 lines, looks like instructions) vs "thin" (≤15 lines, looks like a redirect).
-   d. Extract any relative-path references (./docs/..., docs/...).
-3. Determine canonical:
-   a. If AGENTS.md exists and is fat → AGENTS.md is canonical.
-   b. If AGENTS.md missing but CLAUDE.md is fat → recommend "promote CLAUDE.md → AGENTS.md".
-   c. If multiple fat entry files exist → flag drift; recommend consolidation.
-4. Verify thin-pointer expectation:
-   a. For every entry file that is NOT canonical, check it is thin.
-   b. If thin: pass.
-   c. If fat: flag as drift risk.
-5. For the canonical file, verify required sections:
-   a. "Where to find things" / equivalent
-   b. "Memory primitives" / equivalent
-   c. Build / test / run commands
-   d. Trust boundaries (optional but recommended)
-   e. Date or "Last reviewed" line.
-```
-
-## Output shape (the gap-report row)
-
-For each finding, emit a row like:
-
-```markdown
-- **MISSING — AGENTS.md** (severity: high)
-  - The repo has no `AGENTS.md` at the root.
-  - `CLAUDE.md` exists and is 240 lines, looks canonical.
-  - **Recommendation:** rename `CLAUDE.md` → `AGENTS.md`, then create a thin `CLAUDE.md` redirecting to it.
-  - **Recipe:** see `recipes/audit-existing-repo.md` step 4.
-
-- **DRIFT — CLAUDE.md vs .cursorrules** (severity: medium)
-  - Both files contain non-trivial instructions but differ.
-  - `CLAUDE.md`: 180 lines, lists `pnpm` build commands.
-  - `.cursorrules`: 95 lines, lists `npm` build commands. Probably stale.
-  - **Recommendation:** consolidate into AGENTS.md; demote both to thin pointers.
-
-- **NAKED ENTRY — AGENTS.md** (severity: medium)
-  - `AGENTS.md` exists but has no "Where to find things" section.
-  - Doc subfolders exist (`.brain/adrs/`, `PLAN.md`) but are unreachable from the entry file.
-  - **Recommendation:** add a "Where to find things" section listing the subfolders. See `standards/agents-md-spec.md`.
-```
-
-## Severity rubric
-
-| Severity | Meaning | Examples |
-|---|---|---|
-| **Critical** | Entry-file is missing entirely; no LLM agent can read this repo | No AGENTS.md AND no CLAUDE.md AND no README.md with instructions |
-| **High** | Canonical entry-file missing; substantive content lives in a non-canonical file | No AGENTS.md, but fat CLAUDE.md exists |
-| **Medium** | Canonical exists but is incomplete or has drift risk | Fat AGENTS.md + fat CLAUDE.md (drift); naked AGENTS.md (no pointers) |
-| **Low** | Canonical and pointers correct, but missing dated metadata | AGENTS.md has no `_Last reviewed:_` line |
-
-## Cross-references
-
-- AGENTS.md spec details: `../standards/agents-md-spec.md`
-- CLAUDE.md thin-pointer pattern: `../standards/claude-md-convention.md`
-- Pointer validation (next audit pattern): `pointer-validation.md`
-- Full audit recipe: `../recipes/audit-existing-repo.md`