@sabaiway/agent-workflow-kit 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -4,7 +4,39 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
-## 1.11.0 — One source of truth: the kit reads the methodology live from the installed engine
+## 1.12.0 — See the whole family, and uninstall it cleanly
+
+Two new in-agent modes, built on a single **unified family registry**. `/agent-workflow-kit status`
+shows — read-only — which family members (kit / memory / engine / the two bridges) are installed, at
+what version, and (in a project) what is deployed (`docs/ai`, the version stamps, the hidden-mode
+fence). `/agent-workflow-kit uninstall` is the **guarded teardown**: it reverses what `init` and
+`setup` placed — installed skill dirs + bridge wrappers, and in a project the hidden-mode fence + the
+marker pre-commit hook — but it **never deletes user-authored content** (`docs/ai`, `AGENTS.md`, your
+`.claude/settings.json`); for those it prints the exact commands and lets you run them. It removes only
+what is **provably ours** (a valid manifest, name + kind match; a wrapper symlink that points at our
+source) — anything else is left untouched — and it **previews with `--dry-run` and preflights before
+it touches anything**, so a conflict makes zero changes. The deployment-lineage head stays **`1.3.0`**
+(no `docs/ai` structural change; no migration file). See **AD-017**.
+
+### Added
+- `tools/family-registry.mjs` — the unified, kit-owned registry over every family member (the
+  `KNOWN_BACKENDS` precedent, generalized to all five). Resolves each member's `detect.installed`,
+  manifest health, and installed version; powers `/agent-workflow-kit status`. A drift-guard test pins
+  it to the five in-repo `capability.json` files.
+- `tools/uninstall.mjs` — the guarded uninstaller behind `/agent-workflow-kit uninstall`: a pure
+  classifier (`buildPlan`) + a preflight-then-mutate executor (`executePlan`). Four surface classes —
+  safe-remove (provably-ours skill dirs), managed-marker (wrapper symlinks / the hidden-mode fence /
+  the marker hook), report-only (never-deleted user content), and stop (present-but-not-ours).
+- `tools/fs-safe.mjs` gains `removeTreeManaged` + `unlinkManaged` — the symlink-safe inverses of
+  `copyTreeRefresh` / `linkManaged` (refuse to delete through a symlink or outside the root; remove
+  only a symlink whose target is ours).
+
+### Changed
+- `tools/manifest/validate.mjs` exports `readAuthoritativeVersion` so the registry reports an installed
+  member's version from the same authoritative source the validator checks.
+- The kit's own `capability.json` now declares `uninstall.removeResolved` (uniform with memory +
+  engine); the guarded uninstaller's behavior matches it — it removes exactly the resolved
+  `detect.installed` dir, so the long-declared teardown is now realized, not just documented.
 
 The bounded methodology fragment the kit writes into a project's `AGENTS.md` is now read **live from
 the installed `@sabaiway/agent-workflow-engine`** — the family's single source of truth. The kit's old

package/README.md

@@ -220,6 +220,8 @@ command is printed).
 | `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, preserves your authored memory, applies migrations, re-stamps — then prints a **read-only** one-line backend-status line (what's set up vs missing); never installs a bridge — set one up with `/agent-workflow-kit setup` |
 | `/agent-workflow-kit backends` | any time | **read-only** check of the optional execution-backends (the `codex` / `agy` bridges): what's set up vs missing and the next step. Never writes, never commits, never runs a subscription CLI (credentials = marker-file presence, not a live login). |
 | `/agent-workflow-kit setup [backend]` | opt-in, any time | **link-only** auto-setup of a bridge: places the bundled bridge skill (only into an absent / empty / managed dir — never overwrites an unmanaged one) + links its wrappers onto `PATH` via managed symlinks (idempotent; refuses to clobber a non-symlink; try `--dry-run` to preview). The binary install + the one-time subscription login stay **manual**: it prints the exact **login** command and points the binary install at each bridge's `setup/README.md`. POSIX wrappers — on Windows use WSL. Never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit status` | any time | **read-only** view of the whole family: which members (kit / memory / engine / the two bridges) are installed and at what version, and — with a project — what's deployed (`docs/ai`, the version stamps, and whether the AI files are git-ignored for hidden mode). Never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` / settings — for those it prints the exact `rm` commands to run by hand. Always `--dry-run` first; preflight-then-mutate; never commits. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 
@@ -306,7 +308,9 @@ agent-workflow-kit/
 │   ├── engine-source.mjs     ← live engine fragment read (fail-loud)
 │   ├── detect-backends.mjs    ← read-only backend detector
 │   ├── setup-backends.mjs     ← link-only backend setup
-│   ├── fs-safe.mjs            ← symlink-safe copy/link
+│   ├── fs-safe.mjs            ← symlink-safe copy/link/remove/unlink
+│   ├── family-registry.mjs    ← unified family registry (status)
+│   ├── uninstall.mjs          ← guarded teardown (uninstall)
 │   └── release-scan.mjs       ← attribution / release gate
 ├── bridges/         ← bundled bridge skill mirrors (codex / antigravity)
 ├── launchers/       ← Codex / Devin Desktop / Cursor entries

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.11.0'
+  version: '1.12.0'
 ---
 
 # agent-workflow-kit
@@ -96,6 +96,8 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 - **`/agent-workflow-kit upgrade`** — upgrade an existing deployment to the skill's current `version`.
 - **`/agent-workflow-kit backends`** — read-only environment check: which optional **execution-backends** (the `codex` / `agy` bridges) are set up vs missing. Never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit setup [backend]`** — the **link-only**, opt-in companion to `backends`: place the bundled bridge skill + link its wrappers onto `PATH`. **In-agent only** — `init` (npx) never places bridges. The binary install + the interactive subscription login stay **manual** (it prints the exact commands); idempotent; refuses to clobber a non-symlink; never commits, never runs a subscription CLI.
+- **`/agent-workflow-kit status`** — read-only view of the **whole family**: which members (kit / memory / engine / the two bridges) are installed, at what version, and — in a project — what is deployed (`docs/ai`, the version stamps, the hidden-mode fence). Never writes, never commits, never runs a subscription CLI.
+- **`/agent-workflow-kit uninstall`** — the **guarded teardown** companion to `init`/`setup`. Removes what they placed — installed skill dirs + the bridge wrappers — and, in a project, reverses the hidden-mode fence + the marker pre-commit hook. **Never deletes user-authored content** (`docs/ai`, `AGENTS.md`, `.claude/settings.json`): it prints the exact commands for you to run by hand. `--dry-run` first, always; preflight-then-mutate; never commits.
 
 ### Version status & the two axes — surface this on every invocation
 
@@ -235,6 +237,36 @@ For each backend it:
 
 **Exit codes:** `0` = done / already set up / only manual steps remain (guidance is never a failure); **non-zero** = a STOP (a dir/symlink it refuses to clobber), a bad argument, a missing bundle, or a native fs error (the underlying reason is preserved in the message).
 
+### Mode: status
+
+Read-only. Answers *"which family members are installed (and at what version), and what is deployed in this project?"* across the **whole family** — the unified registry behind it (`tools/family-registry.mjs`) aggregates every member's `capability.json`. It **never writes, never commits, and never runs a subscription CLI**.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs [--dir <project>]` and present its two-axis table:
+
+1. **Skill axis (always):** per member — `installed` + the manifest health (`ok` / `not-installed` / `foreign` / `stub` / `invalid-manifest` / `unsupported-schema`, the same precedence the backend detector uses) + the installed version (read from the member's own `SKILL.md`, the authoritative source).
+2. **Deploy axis (`--dir <project>`):** the deployment stamps (`docs/ai/.workflow-version`, `.memory-version`), whether `docs/ai/` exists, and whether the hidden-mode managed fence is present.
+
+State plainly that the two version axes stay decoupled (an installed *skill* version is not a project's deployment-lineage stamp — see *Version status & the two axes*). The installed version reflects whatever is on disk under `~/.claude/skills/…`; a stale install shows its real (older) version, honestly.
+
+### Mode: uninstall
+
+The **guarded teardown** — the inverse of `init` (the kit + engine skills) + `setup` (the bridges) + a hidden deploy. **In-agent, opt-in**, and built around one hard rule: **it never deletes user-authored content.** Run **`--dry-run` first, always**, show the user the classified plan in plain language, get explicit consent, then re-run with `--yes`. It **never commits**.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/uninstall.mjs [<member>] [--dir <project>] [--bindir <path>] [--dry-run | --yes]`:
+
+- `<member>` — limit the skill axis to one member (`agent-workflow-kit` / `-memory` / `-engine` / a bridge); omit for the **whole family**.
+- `--dir <project>` — also reverse the **project-deployment** surfaces in `<project>`.
+- `--bindir <path>` — where the bridge wrappers were linked (default `~/.local/bin`, mirrors `setup`).
+- `--dry-run` — print the plan and change **nothing** (run this first). `--yes` — apply the **auto-removable** set.
+
+It classifies every surface into four classes and acts accordingly:
+
+- **remove** (safe) — an installed skill dir that is **provably ours** (valid manifest, `name`+`kind` match). A dir present but **not provably ours** (`foreign`/`stub`/`invalid`/unreadable) → **STOP**: left untouched **and reported**, while the teardown still removes the members that ARE ours (a not-ours surface is never clobbered, and never blocks removing the rest — the per-item `setup` posture). **Preflight-then-mutate:** if a mutable surface **changed since the dry-run** (a skill no longer ours, a wrapper turned foreign, a hook that lost our marker, a malformed fence), the run **aborts with zero changes**.
+- **reverse** (managed-marker) — a bridge **wrapper symlink that points at our source** (a foreign/non-symlink one → STOP); the hidden-mode **managed fence** (via the existing `--unhide` path — only the fenced lines); a **pre-commit hook carrying our marker** (an unmarked / user hook → left + reported).
+- **KEEP — never deleted** (report-only) — `docs/ai`, `AGENTS.md`, `CLAUDE.md`, `docs/plans`, and the `.claude/settings.json` `includeCoAuthoredBy` edit. The tool **prints the exact `rm` / `git rm --cached` commands**; the **user** runs them. Surface this in plain language; never delete on their behalf.
+
+**Shared globals:** removing `agent-workflow-memory` / `agent-workflow-engine` / a bridge removes a **global** skill that another project on the machine may use — say so before applying. **Windows:** the wrappers are POSIX; the skill-dir + project arms still work, the wrapper arm reports *use WSL*.
+
 ---
 
 ## Gotchas
@@ -251,6 +283,7 @@ The non-obvious traps — scan these before bootstrapping or upgrading. Each is
 - **Conversational language never translates artifacts.** It governs *dialogue only*. Code, identifiers, paths, commands, log output, abbreviations, and every deployed `docs/ai/` / `AGENTS.md` file stay in their source language. See [Communication contract](references/contracts.md#communication-contract).
 - **Never auto-commit.** Report quality-gate results and wait for explicit approval — in both modes.
 - **Never leak kit internals to the user.** No ADR ids, tool / function / operation names (`reconcile`, `inject`, `ensureSlot`), marker / slot / fragment / anchor terminology, or verbatim tool stderr in anything the user reads. Translate every tool outcome into plain language a third-party user — who has never read this `SKILL.md` — can understand and act on (e.g. the cap-refusal report in *Mode: upgrade* step 3).
+- **Uninstall never deletes user-authored content, and dry-runs first.** `/agent-workflow-kit uninstall` removes only what is **provably ours** (a managed skill dir / wrapper symlink / fenced block / marker hook) and **prints — never runs** the `rm` / `git rm --cached` for `docs/ai`, the entry-point docs, and `.claude/settings.json`. Always run `--dry-run` first, show the plan, get consent, then `--yes`. A skill dir or symlink that is not provably ours is a STOP, never a clobber (the `setup` posture, inverted). Removing a shared global (memory/engine/a bridge) may affect another project — say so.
 
 ---
 
@@ -306,6 +339,6 @@ Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
 - [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness + index-freshness gate, 3-tier archive, hook installer) and their unit tests.
 - [`migrations/`](migrations/) — per-version upgrade steps; see `migrations/README.md`.
 - [`launchers/`](launchers/) — run the bootstrapper from non-Claude agents (`SKILL.md` is a native Codex skill; a Devin Desktop workflow launcher + install script). See `launchers/README.md`.
-- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `engine-source.mjs` (the bounded slot reconciliation — ensure-slot / inject-if-empty / cap; the fragment is read **live** from the installed `agent-workflow-engine` via `engine-source.mjs` — the family's one source of truth, no bundled mirror; fail-loud when the engine is needed but absent), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link primitives both `setup-backends` and the npx installer use), `known-footprint.mjs` + `hide-footprint.mjs` (the **hidden-mode** registry + the single hide-writer behind step 9 / the upgrade reconcile — one managed block in the **project-local** `.git/info/exclude` covering the full AI/agent footprint; pinned by `known-footprint.test.mjs` drift-guard + `hide-footprint.test.mjs` / `.integration.test.mjs`), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
+- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `engine-source.mjs` (the bounded slot reconciliation — ensure-slot / inject-if-empty / cap; the fragment is read **live** from the installed `agent-workflow-engine` via `engine-source.mjs` — the family's one source of truth, no bundled mirror; fail-loud when the engine is needed but absent), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link/**remove/unlink** primitives that `setup-backends`, the npx installer, and the uninstaller use), `known-footprint.mjs` + `hide-footprint.mjs` (the **hidden-mode** registry + the single hide-writer behind step 9 / the upgrade reconcile — one managed block in the **project-local** `.git/info/exclude` covering the full AI/agent footprint; pinned by `known-footprint.test.mjs` drift-guard + `hide-footprint.test.mjs` / `.integration.test.mjs`), `family-registry.mjs` (the **unified family registry** behind `/agent-workflow-kit status` — aggregates every member's `capability.json`; pinned by a `family-registry.test.mjs` drift-guard), `uninstall.mjs` (the **guarded teardown** behind `/agent-workflow-kit uninstall` — classify each surface, preflight-then-mutate, never delete user-authored content), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
 - [`capability.json`](capability.json) — the kit's own `agent-workflow` family manifest (`kind: composition-root`).
 - [`CHANGELOG.md`](CHANGELOG.md) — version history of this kernel.

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "provides": [],
   "roles": {},
   "detect": {
@@ -15,6 +15,10 @@
     "deployed": { "file": "docs/ai/.workflow-version" }
   },
   "install": { "npm": "@sabaiway/agent-workflow-kit" },
+  "uninstall": {
+    "removeResolved": "detect.installed",
+    "note": "the guarded `/agent-workflow-kit uninstall` removes the resolved detect.installed dir — never user-authored docs/ai (those are reported, not deleted)"
+  },
   "cost": "none",
   "quota": null,
   "provenance": { "author": "sabaiway", "source": "github:sabaiway/agent-workflow" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/tools/family-registry.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+// family-registry.mjs — the unified, kit-owned registry over EVERY agent-workflow family member.
+//
+// Until now "who the members are" was split across three disjoint kit-owned tables: KNOWN_BACKENDS
+// (the 2 bridges, detect-backends.mjs), KIT_OWN_PATHS/KNOWN_FOOTPRINT (the hidden-mode paths,
+// known-footprint.mjs), and the 5 per-member capability.json files. This module is the single
+// authoritative aggregation: it answers "what is installed, what version, what kind" (the SKILL
+// axis) and "what is deployed in this project" (the deploy axis). It is the substrate the read-only
+// `/agent-workflow-kit status` mode and the guarded `/agent-workflow-kit uninstall` both consume.
+//
+// Source of truth = the in-tool FAMILY_MEMBERS table (the AD-008 KNOWN_BACKENDS precedent): a member
+// that is NOT installed has no manifest on disk to read, so the enumeration + detect/install facts
+// must live here. A drift-guard test (family-registry.test.mjs) pins FAMILY_MEMBERS to the 5 in-repo
+// capability.json files, so the table cannot silently drift from the manifests it mirrors.
+//
+// Pure, dependency-injectable (fs/env/home/validator are deps), dependency-free, Node >= 18. No
+// side effects on import (the isDirectRun idiom) — tests import the helpers with nothing run.
+
+import { existsSync, statSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import os from 'node:os';
+import { resolveDir } from './detect-backends.mjs';
+import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
+import { START_MARKER, excludePath } from './hide-footprint.mjs';
+
+// ── manifestState values (the detect-backends precedence, generalized to any member kind) ──────────
+export const NOT_INSTALLED = 'not-installed';
+export const UNSUPPORTED_SCHEMA = 'unsupported-schema';
+export const INVALID_MANIFEST = 'invalid-manifest';
+export const STUB = 'stub';
+export const FOREIGN = 'foreign';
+export const OK = 'ok';
+// The marker could not be probed (a non-ENOENT fs error — EACCES/EIO). Surfaced explicitly instead of
+// being masked as not-installed (no silent failure); uninstall treats it as "do not touch" (skip).
+export const UNKNOWN = 'unknown';
+
+// ── the unified registry ───────────────────────────────────────────────────────
+// One entry per family member. `installed` is the detect.installed spec (env + home-relative default
+// + marker file); `deployed` is the project-relative stamp a deploy writes (kit + memory only);
+// `npm` is the install package (null for the bridges, which are placed by `setup`, not npm);
+// `wrapperCmds` is the deduped roles[].cmd set the `setup` linker creates on PATH (bridges only).
+// Kept in lockstep with the 5 in-repo capability.json by the drift-guard test. The two release skills
+// (release-engineering / release-marketing) are deliberately NOT here — they are not family members
+// (AD-013): no capability.json, not in the kit tarball, not in the role vocabulary.
+export const FAMILY_MEMBERS = [
+  {
+    name: 'agent-workflow-kit',
+    kind: 'composition-root',
+    installed: { env: 'AGENT_WORKFLOW_KIT_DIR', default: '~/.claude/skills/agent-workflow-kit', file: 'SKILL.md' },
+    deployed: { file: 'docs/ai/.workflow-version' },
+    npm: '@sabaiway/agent-workflow-kit',
+    wrapperCmds: [],
+  },
+  {
+    name: 'agent-workflow-memory',
+    kind: 'memory-substrate',
+    installed: { env: 'AGENT_WORKFLOW_MEMORY_DIR', default: '~/.claude/skills/agent-workflow-memory', file: 'SKILL.md' },
+    deployed: { file: 'docs/ai/.memory-version' },
+    npm: '@sabaiway/agent-workflow-memory',
+    wrapperCmds: [],
+  },
+  {
+    name: 'agent-workflow-engine',
+    kind: 'methodology-engine',
+    installed: { env: 'AGENT_WORKFLOW_ENGINE_DIR', default: '~/.claude/skills/agent-workflow-engine', file: 'SKILL.md' },
+    deployed: null,
+    npm: '@sabaiway/agent-workflow-engine',
+    wrapperCmds: [],
+  },
+  {
+    name: 'codex-cli-bridge',
+    kind: 'execution-backend',
+    installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' },
+    deployed: null,
+    npm: null,
+    wrapperCmds: ['codex-exec', 'codex-review'],
+  },
+  {
+    name: 'antigravity-cli-bridge',
+    kind: 'execution-backend',
+    installed: { env: 'ANTIGRAVITY_CLI_BRIDGE_DIR', default: '~/.claude/skills/antigravity-cli-bridge', file: 'SKILL.md' },
+    deployed: null,
+    npm: null,
+    wrapperCmds: ['agy-run'],
+  },
+];
+
+// A GLOBAL skill (lives under ~/.claude/skills) may be shared by other projects on the host — the
+// uninstaller warns before removing one (there is no cross-project dependency tracking). All current
+// members are global skills; the field is explicit so the warning is data-driven, not hardcoded.
+export const isGlobalSkill = (member) => member.kind !== undefined; // every member is a global skill today
+
+// ── pure probes ──────────────────────────────────────────────────────────────────
+// Wrapped marker probe → 'present' (a regular file) | 'absent' (ENOENT / not a file) | 'unknown' (a
+// non-ENOENT fs error, e.g. EACCES). 'unknown' is NOT collapsed to 'absent': a permission error must
+// surface, never be masked as not-installed (no silent failure) — and uninstall then leaves it alone.
+const probeMarker = (path, deps = {}) => {
+  const exists = deps.exists ?? existsSync;
+  const stat = deps.stat ?? statSync;
+  try {
+    if (!exists(path)) return 'absent';
+    return stat(path).isFile() ? 'present' : 'absent';
+  } catch (err) {
+    return err && err.code === 'ENOENT' ? 'absent' : 'unknown';
+  }
+};
+
+// Pure manifestState classifier — the detect-backends precedence, generalized to a member's own
+// expected name + kind: not-installed → unsupported-schema → invalid-manifest → stub → foreign → ok.
+const classifyState = (markerPresent, report, member) => {
+  if (!markerPresent) return NOT_INSTALLED;
+  if (report.result === UNSUPPORTED) return UNSUPPORTED_SCHEMA;
+  if (report.result === INVALID) return INVALID_MANIFEST;
+  if (report.available === false) return STUB;
+  if (report.kind !== member.kind || report.name !== member.name) return FOREIGN;
+  return OK;
+};
+
+// ── the SKILL axis ─────────────────────────────────────────────────────────────
+// classifyMember → { name, kind, installed, skillDir, manifestState, version }. Reuses resolveDir
+// (detect-backends), validateManifest + readAuthoritativeVersion (the manifest validator) — one
+// authoritative version reader, no second drifting source. `version` is set only for an `ok` member.
+export const classifyMember = (member, deps = {}) => {
+  const validate = deps.validate ?? validateManifest;
+  const readVersion = deps.readVersion ?? readAuthoritativeVersion;
+  const getenv = deps.getenv ?? process.env;
+  const home = deps.home ?? os.homedir();
+
+  const skillDir = resolveDir({ env: member.installed.env, default: member.installed.default }, getenv, home);
+  const marker = probeMarker(join(skillDir, member.installed.file), deps);
+  // A marker we cannot probe (EACCES/EIO) → 'unknown': reported, but NOT installed (so uninstall never
+  // removes a dir whose ownership it could not verify). Distinct from 'not-installed' (genuinely absent).
+  if (marker === 'unknown') {
+    return { name: member.name, kind: member.kind, installed: false, skillDir, manifestState: UNKNOWN, version: null };
+  }
+  const markerPresent = marker === 'present';
+  const report = markerPresent ? validate(skillDir) : { result: NOT_INSTALLED };
+  const manifestState = classifyState(markerPresent, report, member);
+  const installed = manifestState !== NOT_INSTALLED;
+  const version = manifestState === OK ? readVersion(skillDir).version ?? null : null;
+
+  return { name: member.name, kind: member.kind, installed, skillDir: installed ? skillDir : null, manifestState, version };
+};
+
+export const surveyFamily = (deps = {}) => FAMILY_MEMBERS.map((member) => classifyMember(member, deps));
+
+// ── the DEPLOY axis ──────────────────────────────────────────────────────────────
+// Read a one-line semver stamp (docs/ai/.workflow-version etc.). Returns the trimmed version or null.
+const readStamp = (path, deps = {}) => {
+  const exists = deps.exists ?? existsSync;
+  const read = deps.readFile ?? readFileSync;
+  try {
+    if (!exists(path)) return null;
+    const v = String(read(path, 'utf8')).trim();
+    return v.length ? v : null;
+  } catch {
+    return null;
+  }
+};
+
+// Is our hidden-mode managed fence present? Resolve the exclude file via the SAME git-path-aware path
+// hide-footprint uses (`git rev-parse --git-path info/exclude`), so a linked worktree / submodule is
+// handled correctly (not the hardcoded `.git/info/exclude`). If git is unavailable or this is not a
+// repo, fall back to the conventional path; any read error → not present (best-effort, read-only).
+const hasHiddenFence = (projectDir, deps = {}) => {
+  const exists = deps.exists ?? existsSync;
+  const read = deps.readFile ?? readFileSync;
+  const ep = (() => {
+    try {
+      return excludePath(deps, projectDir);
+    } catch {
+      return join(projectDir, '.git', 'info', 'exclude');
+    }
+  })();
+  try {
+    return exists(ep) && String(read(ep, 'utf8')).includes(START_MARKER);
+  } catch {
+    return false;
+  }
+};
+
+// surveyProject → the deploy axis for a target project dir: the per-member deployment stamps, whether
+// docs/ai/ exists, and whether the hidden-mode fence is present. Pure (fs reads only, all injectable),
+// no git subprocess — the read-only `status` view must never mutate or spawn anything.
+export const surveyProject = (projectDir, deps = {}) => {
+  const exists = deps.exists ?? existsSync;
+  const dir = resolve(projectDir);
+  const stamps = FAMILY_MEMBERS
+    .filter((m) => m.deployed)
+    .map((m) => ({ name: m.name, file: m.deployed.file, version: readStamp(join(dir, m.deployed.file), deps) }));
+  const docsAiPresent = (() => {
+    try {
+      return exists(join(dir, 'docs', 'ai'));
+    } catch {
+      return false;
+    }
+  })();
+  const deployed = stamps.some((s) => s.version != null) || docsAiPresent;
+  return { dir, deployed, docsAiPresent, hiddenFence: hasHiddenFence(dir, deps), stamps };
+};
+
+// ── report ───────────────────────────────────────────────────────────────────────
+const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
+
+export const formatStatus = (family, project = null) => {
+  const lines = ['agent-workflow family — installed skills (skill axis)', ''];
+  for (const m of family) {
+    const ver = m.version ? `v${m.version}` : '—';
+    lines.push(`  ${pad(m.name, 26)}[${pad(m.manifestState, 16)}] ${pad(ver, 10)} ${m.kind}`);
+  }
+  if (project) {
+    lines.push('', `project deployment (${project.dir})`, '');
+    if (!project.deployed) {
+      lines.push('  no agent-workflow deployment detected here (no docs/ai, no version stamp).');
+    } else {
+      for (const s of project.stamps) {
+        lines.push(`  ${pad(s.file, 26)}${s.version ?? '—'}`);
+      }
+      lines.push(`  ${pad('docs/ai present', 26)}${project.docsAiPresent ? 'yes' : 'no'}`);
+      lines.push(`  ${pad('hidden-mode fence', 26)}${project.hiddenFence ? 'present' : 'absent'}`);
+    }
+  }
+  return lines.join('\n');
+};
+
+// ── CLI ────────────────────────────────────────────────────────────────────────
+const parseArgs = (argv) => {
+  const dirFlag = argv.indexOf('--dir');
+  return { help: argv.includes('--help') || argv.includes('-h'), dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined };
+};
+
+const main = (argv) => {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(`family-registry — read-only view of the agent-workflow family.
+
+Usage:
+  node family-registry.mjs [--dir <project>]   # skill axis always; deploy axis when --dir is given
+
+Detection only — never writes, never commits, never runs a subscription CLI.`);
+    return;
+  }
+  const family = surveyFamily();
+  const project = args.dir ? surveyProject(args.dir) : null;
+  console.log(formatStatus(family, project));
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) main(process.argv.slice(2));

package/tools/family-registry.test.mjs

@@ -0,0 +1,189 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  FAMILY_MEMBERS,
+  classifyMember,
+  surveyFamily,
+  surveyProject,
+  NOT_INSTALLED,
+  UNSUPPORTED_SCHEMA,
+  INVALID_MANIFEST,
+  STUB,
+  FOREIGN,
+  OK,
+  UNKNOWN,
+} from './family-registry.mjs';
+import { VALID, INVALID, UNSUPPORTED } from './manifest/validate.mjs';
+import { START_MARKER } from './hide-footprint.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '../..'); // agent-workflow-kit/tools → repo root
+
+// Build classifyMember deps that present the marker, with an injectable validate/readVersion.
+const installedDeps = ({ report, version = '9.9.9', home = '/home/test' }) => ({
+  exists: () => true,
+  stat: () => ({ isFile: () => true }),
+  getenv: {},
+  home,
+  validate: () => report,
+  readVersion: () => ({ version }),
+});
+
+const KIT = FAMILY_MEMBERS.find((m) => m.name === 'agent-workflow-kit');
+
+// ── classifyMember ───────────────────────────────────────────────────────────────
+
+describe('classifyMember', () => {
+  it('marks an absent marker as not-installed (no skillDir, no version)', () => {
+    const r = classifyMember(KIT, { exists: () => false, getenv: {}, home: '/home/test' });
+    assert.equal(r.manifestState, NOT_INSTALLED);
+    assert.equal(r.installed, false);
+    assert.equal(r.skillDir, null);
+    assert.equal(r.version, null);
+  });
+
+  it('classifies a valid matching manifest as ok and reports the authoritative version', () => {
+    const r = classifyMember(KIT, installedDeps({
+      report: { result: VALID, name: 'agent-workflow-kit', kind: 'composition-root', available: true },
+      version: '1.12.0',
+    }));
+    assert.equal(r.manifestState, OK);
+    assert.equal(r.installed, true);
+    assert.equal(r.version, '1.12.0');
+    assert.match(r.skillDir, /\.claude\/skills\/agent-workflow-kit$/);
+  });
+
+  it('classifies a wrong name/kind as foreign (never ours, never removed by uninstall)', () => {
+    const r = classifyMember(KIT, installedDeps({
+      report: { result: VALID, name: 'something-else', kind: 'composition-root', available: true },
+    }));
+    assert.equal(r.manifestState, FOREIGN);
+    assert.equal(r.version, null); // version only for ok
+  });
+
+  it('classifies available:false as a stub', () => {
+    const r = classifyMember(KIT, installedDeps({
+      report: { result: VALID, name: 'agent-workflow-kit', kind: 'composition-root', available: false },
+    }));
+    assert.equal(r.manifestState, STUB);
+  });
+
+  it('maps validator INVALID → invalid-manifest and UNSUPPORTED → unsupported-schema', () => {
+    assert.equal(classifyMember(KIT, installedDeps({ report: { result: INVALID } })).manifestState, INVALID_MANIFEST);
+    assert.equal(classifyMember(KIT, installedDeps({ report: { result: UNSUPPORTED } })).manifestState, UNSUPPORTED_SCHEMA);
+  });
+
+  it('surfaces an EACCES marker probe as "unknown" — never masked as not-installed', () => {
+    const eacces = () => { throw Object.assign(new Error('EACCES'), { code: 'EACCES' }); };
+    const r = classifyMember(KIT, { exists: eacces, getenv: {}, home: '/home/test' });
+    assert.equal(r.manifestState, UNKNOWN);
+    assert.equal(r.installed, false); // not removed — ownership could not be verified
+  });
+
+  it('resolves the skill dir from the env override when set (resolveDir reuse)', () => {
+    const r = classifyMember(KIT, {
+      exists: () => true,
+      stat: () => ({ isFile: () => true }),
+      getenv: { AGENT_WORKFLOW_KIT_DIR: '/custom/kit' },
+      home: '/home/test',
+      validate: () => ({ result: VALID, name: 'agent-workflow-kit', kind: 'composition-root', available: true }),
+      readVersion: () => ({ version: '1.12.0' }),
+    });
+    assert.equal(r.skillDir, '/custom/kit');
+  });
+});
+
+describe('surveyFamily', () => {
+  it('returns one row per member; all not-installed when no markers present', () => {
+    const rows = surveyFamily({ exists: () => false, getenv: {}, home: '/home/test' });
+    assert.equal(rows.length, FAMILY_MEMBERS.length);
+    assert.ok(rows.every((r) => r.manifestState === NOT_INSTALLED));
+  });
+});
+
+// ── surveyProject ────────────────────────────────────────────────────────────────
+
+describe('surveyProject', () => {
+  const projectDeps = ({ files }) => ({
+    exists: (p) => Object.prototype.hasOwnProperty.call(files, p) || Object.keys(files).some((k) => k === p),
+    readFile: (p) => {
+      if (!Object.prototype.hasOwnProperty.call(files, p)) throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+      return files[p];
+    },
+  });
+
+  it('reports deployed + stamps + docs/ai + hidden fence', () => {
+    const dir = '/proj';
+    const files = {
+      [join(dir, 'docs/ai/.workflow-version')]: '1.3.0\n',
+      [join(dir, 'docs/ai/.memory-version')]: '1.1.1\n',
+      [join(dir, 'docs', 'ai')]: '',
+      [join(dir, '.git', 'info', 'exclude')]: `# user rule\n${START_MARKER}\n/AGENTS.md\n`,
+    };
+    const r = surveyProject(dir, projectDeps({ files }));
+    assert.equal(r.deployed, true);
+    assert.equal(r.docsAiPresent, true);
+    assert.equal(r.hiddenFence, true);
+    assert.deepEqual(
+      r.stamps.map((s) => [s.name, s.version]),
+      [['agent-workflow-kit', '1.3.0'], ['agent-workflow-memory', '1.1.1']],
+    );
+  });
+
+  it('reports not-deployed when there is no docs/ai and no stamp', () => {
+    const r = surveyProject('/empty', projectDeps({ files: {} }));
+    assert.equal(r.deployed, false);
+    assert.equal(r.hiddenFence, false);
+    assert.ok(r.stamps.every((s) => s.version === null));
+  });
+});
+
+// ── drift-guard: FAMILY_MEMBERS ⟷ the 5 in-repo capability.json (the AD-008 lockstep pattern) ──────
+
+describe('FAMILY_MEMBERS drift-guard', () => {
+  const readManifest = (memberName) =>
+    JSON.parse(readFileSync(resolve(REPO_ROOT, memberName, 'capability.json'), 'utf8'));
+
+  // deduped roles[].cmd, in first-seen order (mirrors detect-backends' wrapperCmds derivation).
+  const dedupedCmds = (manifest) => {
+    const seen = new Set();
+    const out = [];
+    for (const role of Object.values(manifest.roles ?? {})) {
+      if (role && typeof role.cmd === 'string' && !seen.has(role.cmd)) {
+        seen.add(role.cmd);
+        out.push(role.cmd);
+      }
+    }
+    return out;
+  };
+
+  it('has exactly the five family members and no release skills', () => {
+    assert.equal(FAMILY_MEMBERS.length, 5);
+    const names = FAMILY_MEMBERS.map((m) => m.name);
+    assert.ok(!names.includes('release-engineering'));
+    assert.ok(!names.includes('release-marketing'));
+  });
+
+  for (const member of FAMILY_MEMBERS) {
+    it(`${member.name}: name/kind/detect.installed/deployed/npm/wrapperCmds match the in-repo manifest`, () => {
+      const m = readManifest(member.name);
+      assert.equal(m.name, member.name);
+      assert.equal(m.kind, member.kind);
+
+      assert.equal(m.detect.installed.env, member.installed.env);
+      assert.equal(m.detect.installed.default, member.installed.default);
+      assert.equal(m.detect.installed.file, member.installed.file);
+
+      if (member.deployed) assert.equal(m.detect.deployed.file, member.deployed.file);
+      else assert.equal(m.detect?.deployed ?? null, null);
+
+      if (member.npm) assert.equal(m.install.npm, member.npm);
+      else assert.equal(m.install?.npm ?? null, null);
+
+      assert.deepEqual(dedupedCmds(m), member.wrapperCmds);
+    });
+  }
+});