@rubytech/create-sitedesk-code 0.1.514 → 0.1.515

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-sitedesk-code",
-  "version": "0.1.514",
+  "version": "0.1.515",
   "description": "Install SiteDesk — automated back office for independent building contractors",
   "bin": {
     "create-sitedesk-code": "./dist/index.js"

package/payload/platform/docs/superpowers/plans/2026-07-27-task-2016-disabled-agent-routing.md

@@ -0,0 +1,624 @@
+# Task 2016 — disabled agents leave the admin routing table
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** A specialist the operator disabled carries no `- **specialists:<name>**:` line in `agents/admin/AGENTS.md`, gets it back on enable, and reads as `disabled` rather than `missing file` in `system-status`.
+
+**Architecture:** One rule in one place: `agents-md-bootstrap.sh` treats `<accountDir>/agents-disabled.json` as the operator's intent and withholds a routing line for every name it holds. The disable and enable routes exec that same script after their file move, so prose is right immediately instead of after the next provisioning run. The `system-status` specialist walk moves into its own module that reads the same store and reports `disabled` and `missing file` as different states with separate counts.
+
+**Tech Stack:** bash + python3 (the store parser already used by `provision-account-dir.sh`), TypeScript on Node, Hono routes, vitest.
+
+## Global Constraints
+
+- Spec: `platform/docs/superpowers/specs/2026-07-27-task-2016-disabled-agent-routing-design.md`.
+- All paths below are relative to `maxy-code/` inside the worktree.
+- A store entry maps to a routing line by stripping `.md`. One rule, no branch.
+- An unreadable store withholds nothing, matching `provision-account-dir.sh:293`.
+- The existing `  [admin-bootstrap] AGENTS.md specialists=<n> appended=<m> existing=<k>` line stays byte-identical; the current suite asserts its counts.
+- `platform/plugins/admin/skills/platform-architecture/SKILL.md` is generated by `scripts/assemble-architecture-skill.mjs` from the docs corpus. Never hand-edit it. Doc changes go in `platform/plugins/docs/references/admin-ui.md`.
+- Commit trailers: `Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>` and `Session: a2b8f556-8297-4184-bf57-59b078a8015d`.
+
+---
+
+## File Structure
+
+| File | Responsibility |
+|------|----------------|
+| `platform/scripts/lib/agents-md-bootstrap.sh` (modify) | Reconcile specialist lines against the disabled store; emit the `op=specialist-lines` line. |
+| `platform/scripts/__tests__/agents-md-bootstrap.test.sh` (modify) | Cases for withhold, restore, malformed store. |
+| `platform/plugins/admin/mcp/src/specialist-registry.ts` (create) | Classify AGENTS.md entries as `ok` / `disabled (operator)` / `missing file` and count them. |
+| `platform/plugins/admin/mcp/src/__tests__/specialist-registry.test.ts` (create) | Cover the three statuses and the two counts. |
+| `platform/plugins/admin/mcp/src/index.ts` (modify, 508-538) | Call the module instead of classifying inline. |
+| `platform/ui/server/routes/admin/agents.ts` (modify) | Exec the bootstrap after disable and enable; report `routingReconciled`. |
+| `platform/ui/server/routes/admin/__tests__/agents.test.ts` (modify) | Prove the line disappears on disable and returns on enable. |
+| `platform/plugins/docs/references/admin-ui.md` (modify, 209-241) | Document the reconcile and the new response field. |
+
+---
+
+### Task 1: The bootstrap reconciles against the disabled store
+
+**Files:**
+- Modify: `platform/scripts/lib/agents-md-bootstrap.sh`
+- Test: `platform/scripts/__tests__/agents-md-bootstrap.test.sh`
+
+**Interfaces:**
+- Consumes: `<accountDir>/agents-disabled.json`, shape `{ "disabled": ["<basename>.md", …] }`, written by `platform/ui/server/routes/admin/agents.ts`.
+- Produces: stdout line `  [agents-md] op=specialist-lines account=<id8> kept=<n> withheld=<comma-list|none|store-unreadable>`. Task 3 relies on this script being callable as `bash <PLATFORM_ROOT>/scripts/lib/agents-md-bootstrap.sh <accountDir>`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `platform/scripts/__tests__/agents-md-bootstrap.test.sh`, immediately before the final summary block that prints `PASS`/`FAIL` counts:
+
+```bash
+# Case 7 (Task 2016) — a name in the disabled store gets no routing line.
+TMP=$(make_account)
+bash "$BOOTSTRAP" "$TMP" >/dev/null
+printf '{"disabled":["beta-specialist.md"]}\n' > "$TMP/agents-disabled.json"
+OUT=$(bash "$BOOTSTRAP" "$TMP")
+assert_not_contains "$TMP/agents/admin/AGENTS.md" "- **specialists:beta-specialist**: " "withhold:beta-line-gone"
+assert_contains "$TMP/agents/admin/AGENTS.md" "- **specialists:alpha-specialist**: " "withhold:alpha-kept"
+assert_contains "$TMP/agents/admin/AGENTS.md" "- **specialists:gamma-specialist**: " "withhold:gamma-kept"
+assert_matches "$OUT" "op=specialist-lines account=[^ ]+ kept=2 withheld=beta-specialist" "withhold:log-line"
+
+# Case 8 (Task 2016) — clearing the store restores the line on the next run.
+printf '{"disabled":[]}\n' > "$TMP/agents-disabled.json"
+OUT=$(bash "$BOOTSTRAP" "$TMP")
+assert_contains "$TMP/agents/admin/AGENTS.md" "- **specialists:beta-specialist**: " "restore:beta-back"
+assert_matches "$OUT" "op=specialist-lines account=[^ ]+ kept=3 withheld=none" "restore:log-line"
+rm -rf "$TMP"
+
+# Case 9 (Task 2016) — a malformed store removes nothing and says so.
+TMP=$(make_account)
+bash "$BOOTSTRAP" "$TMP" >/dev/null
+printf '{ not json' > "$TMP/agents-disabled.json"
+OUT=$(bash "$BOOTSTRAP" "$TMP")
+assert_contains "$TMP/agents/admin/AGENTS.md" "- **specialists:alpha-specialist**: " "badstore:alpha-kept"
+assert_contains "$TMP/agents/admin/AGENTS.md" "- **specialists:beta-specialist**: " "badstore:beta-kept"
+assert_matches "$OUT" "op=specialist-lines account=[^ ]+ kept=3 withheld=store-unreadable" "badstore:log-line"
+rm -rf "$TMP"
+
+# Case 10 (Task 2016) — no store on disk is the cold-install path: nothing withheld.
+TMP=$(make_account)
+OUT=$(bash "$BOOTSTRAP" "$TMP")
+assert_matches "$OUT" "op=specialist-lines account=[^ ]+ kept=3 withheld=none" "nostore:log-line"
+rm -rf "$TMP"
+```
+
+- [ ] **Step 2: Run the suite to verify the new cases fail**
+
+Run: `bash platform/scripts/__tests__/agents-md-bootstrap.test.sh`
+Expected: FAIL. The `withhold:*`, `restore:*`, `badstore:*` and `nostore:*` assertions fail because the script neither removes lines nor prints an `op=specialist-lines` line; every pre-existing case still passes.
+
+- [ ] **Step 3: Implement the reconcile**
+
+In `platform/scripts/lib/agents-md-bootstrap.sh`, extend the header comment after the existing paragraph about preserved lines:
+
+```bash
+# A name in <account_dir>/agents-disabled.json gets no routing line: an existing
+# one is removed and the append loop skips it. The store is the operator's
+# intent, so this holds even in the drift state where the file is still live
+# (the standing agent-parity check is what reports that drift). An unreadable
+# store withholds nothing, matching provision-account-dir.sh.
+#
+# Second stdout line, same two-space indent:
+#   "  [agents-md] op=specialist-lines account=<id8> kept=<n> withheld=<comma-list|none|store-unreadable>"
+```
+
+Insert this block after the `if [ ! -f "$AGENTS_MD" ]` bootstrap block (after line 28) and before `_specialists=0`:
+
+```bash
+# --- Disabled-agent reconcile (Task 2016) ------------------------------------
+_store="$ACCOUNT_DIR/agents-disabled.json"
+_withheld_names=""
+_withheld_field="none"
+if [ -f "$_store" ]; then
+  if _withheld_names=$(python3 -c '
+import json, sys
+try:
+    parsed = json.load(open(sys.argv[1]))
+except Exception:
+    raise SystemExit(1)
+names = parsed.get("disabled")
+if not isinstance(names, list):
+    raise SystemExit(1)
+for n in sorted(names):
+    if isinstance(n, str) and n.endswith(".md") and "/" not in n and ".." not in n:
+        print(n[:-3])
+' "$_store" 2>/dev/null); then
+    if [ -n "$_withheld_names" ]; then
+      _withheld_field=$(echo "$_withheld_names" | paste -sd, -)
+    fi
+  else
+    _withheld_names=""
+    _withheld_field="store-unreadable"
+  fi
+fi
+
+_is_withheld() {
+  [ -n "$_withheld_names" ] || return 1
+  printf '%s\n' "$_withheld_names" | grep -qxF -- "$1"
+}
+
+if [ -n "$_withheld_names" ]; then
+  while IFS= read -r _w; do
+    [ -n "$_w" ] || continue
+    if grep -qE "^- \*\*specialists:${_w}\*\*:" "$AGENTS_MD"; then
+      grep -vE "^- \*\*specialists:${_w}\*\*:" "$AGENTS_MD" > "$AGENTS_MD.tmp" || true
+      mv "$AGENTS_MD.tmp" "$AGENTS_MD"
+    fi
+  done <<< "$_withheld_names"
+fi
+```
+
+In the walk loop, add the skip immediately after `[ -z "$_name" ] && continue` (line 40) so a withheld name is neither counted nor appended:
+
+```bash
+  if _is_withheld "$_name"; then continue; fi
+```
+
+After the existing `echo "  [admin-bootstrap] …"` line, add:
+
+```bash
+_kept=$(grep -cE '^- \*\*specialists:' "$AGENTS_MD" || true)
+_id8=$(basename "$ACCOUNT_DIR" | cut -c1-8)
+echo "  [agents-md] op=specialist-lines account=$_id8 kept=$_kept withheld=$_withheld_field"
+```
+
+- [ ] **Step 4: Run the suite to verify it passes**
+
+Run: `bash platform/scripts/__tests__/agents-md-bootstrap.test.sh`
+Expected: every case passes, `FAIL=0`, including the pre-existing cases 1-6 unchanged.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add maxy-code/platform/scripts/lib/agents-md-bootstrap.sh maxy-code/platform/scripts/__tests__/agents-md-bootstrap.test.sh
+git commit -m "$(cat <<'EOF'
+fix(2016): withhold routing lines for disabled specialists
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+Session: a2b8f556-8297-4184-bf57-59b078a8015d
+EOF
+)"
+```
+
+---
+
+### Task 2: `system-status` separates disabled from missing
+
+**Files:**
+- Create: `platform/plugins/admin/mcp/src/specialist-registry.ts`
+- Create: `platform/plugins/admin/mcp/src/__tests__/specialist-registry.test.ts`
+- Modify: `platform/plugins/admin/mcp/src/index.ts:508-538`
+
+**Interfaces:**
+- Consumes: `<accountDir>/agents-disabled.json` (same shape as Task 1), `<accountDir>/agents/admin/AGENTS.md`, `<accountDir>/specialists/agents/`.
+- Produces: `classifySpecialists(opts: { agentsMd: string; specialistsAgentsDir: string; accountDir: string; chromeUp: boolean }): SpecialistRegistryReport` where `SpecialistRegistryReport = { lines: string[]; registered: number; missing: number; disabled: number }`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `platform/plugins/admin/mcp/src/__tests__/specialist-registry.test.ts`:
+
+```ts
+// Task 2016 — an agent the operator disabled reads as disabled, not as a
+// missing file. A `missing file` line for a name in the store is the failure
+// this suite exists to catch.
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { classifySpecialists } from "../specialist-registry.js";
+
+let accountDir: string;
+
+const AGENTS_MD = [
+  "# Installed Roles",
+  "",
+  "- **specialists:live-one**: Does live work.",
+  "- **specialists:switched-off**: Was switched off.",
+  "- **specialists:never-arrived**: Never delivered.",
+  "",
+].join("\n");
+
+beforeEach(() => {
+  accountDir = mkdtempSync(join(tmpdir(), "spec-registry-"));
+  mkdirSync(join(accountDir, "specialists", "agents"), { recursive: true });
+  writeFileSync(join(accountDir, "specialists", "agents", "live-one.md"), "---\nname: live-one\n---\n");
+  writeFileSync(
+    join(accountDir, "agents-disabled.json"),
+    JSON.stringify({ disabled: ["switched-off.md"] }),
+  );
+});
+
+afterEach(() => rmSync(accountDir, { recursive: true, force: true }));
+
+describe("classifySpecialists", () => {
+  const run = (chromeUp = true) =>
+    classifySpecialists({
+      agentsMd: AGENTS_MD,
+      specialistsAgentsDir: join(accountDir, "specialists", "agents"),
+      accountDir,
+      chromeUp,
+    });
+
+  it("reports a live file as ok", () => {
+    expect(run().lines).toContain("  live-one: ok");
+  });
+
+  it("reports a store name as disabled, never as a missing file", () => {
+    const report = run();
+    expect(report.lines).toContain("  switched-off: disabled (operator)");
+    expect(report.lines.join("\n")).not.toMatch(/switched-off: missing file/);
+  });
+
+  it("reports an absent file the store does not name as a missing file", () => {
+    expect(run().lines).toContain("  never-arrived: missing file");
+  });
+
+  it("counts missing and disabled separately", () => {
+    const report = run();
+    expect(report.registered).toBe(3);
+    expect(report.missing).toBe(1);
+    expect(report.disabled).toBe(1);
+  });
+
+  it("keeps the chrome degradation for a live personal-assistant", () => {
+    writeFileSync(join(accountDir, "specialists", "agents", "personal-assistant.md"), "---\n");
+    const report = classifySpecialists({
+      agentsMd: "- **specialists:personal-assistant**: Browses.\n",
+      specialistsAgentsDir: join(accountDir, "specialists", "agents"),
+      accountDir,
+      chromeUp: false,
+    });
+    expect(report.lines).toContain("  personal-assistant: degraded — chrome not running");
+    expect(report.missing).toBe(0);
+  });
+
+  it("treats an unreadable store as naming nothing", () => {
+    writeFileSync(join(accountDir, "agents-disabled.json"), "{ not json");
+    const report = run();
+    expect(report.lines).toContain("  switched-off: missing file");
+    expect(report.disabled).toBe(0);
+    expect(report.missing).toBe(2);
+  });
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `cd platform/plugins/admin/mcp && npx vitest run src/__tests__/specialist-registry.test.ts`
+Expected: FAIL — `Failed to resolve import "../specialist-registry.js"`.
+
+- [ ] **Step 3: Write the module**
+
+Create `platform/plugins/admin/mcp/src/specialist-registry.ts`:
+
+```ts
+// Task 2016 — the specialist half of `system-status`.
+//
+// Disabling an agent MOVES its file out of `specialists/agents/` (Task 1996),
+// so a walk of AGENTS.md against that directory sees an absent file and, before
+// this module, called it `missing file` — an operator action rendered as an
+// install fault. The disabled store is what tells the two apart.
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export interface SpecialistRegistryReport {
+  /** One `  <name>: <status>` line per AGENTS.md entry, in file order. */
+  lines: string[];
+  registered: number;
+  missing: number;
+  disabled: number;
+}
+
+/** Basenames the operator switched off. An unreadable store names nothing:
+ *  a corrupt file is not evidence that an agent was disabled, and the absent
+ *  file stays `missing file`, which is the honest answer when the store cannot
+ *  be read. */
+function readDisabledStore(accountDir: string): Set<string> {
+  const p = resolve(accountDir, "agents-disabled.json");
+  if (!existsSync(p)) return new Set();
+  try {
+    const parsed = JSON.parse(readFileSync(p, "utf-8")) as { disabled?: unknown };
+    if (!Array.isArray(parsed.disabled)) return new Set();
+    return new Set(parsed.disabled.filter((x): x is string => typeof x === "string"));
+  } catch {
+    return new Set();
+  }
+}
+
+export function classifySpecialists(opts: {
+  agentsMd: string;
+  specialistsAgentsDir: string;
+  accountDir: string;
+  chromeUp: boolean;
+}): SpecialistRegistryReport {
+  const entries = opts.agentsMd.match(/^- \*\*specialists:([^*]+)\*\*/gm) ?? [];
+  const disabled = readDisabledStore(opts.accountDir);
+  const lines: string[] = [];
+  let missingCount = 0;
+  let disabledCount = 0;
+
+  for (const entry of entries) {
+    const nameMatch = entry.match(/specialists:([^*]+)/);
+    if (!nameMatch) continue;
+    const name = nameMatch[1];
+    let status: string;
+    if (existsSync(join(opts.specialistsAgentsDir, `${name}.md`))) {
+      status = name === "personal-assistant" && !opts.chromeUp
+        ? "degraded — chrome not running"
+        : "ok";
+    } else if (disabled.has(`${name}.md`)) {
+      status = "disabled (operator)";
+      disabledCount++;
+    } else {
+      status = "missing file";
+      missingCount++;
+    }
+    lines.push(`  ${name}: ${status}`);
+  }
+
+  return { lines, registered: lines.length, missing: missingCount, disabled: disabledCount };
+}
+```
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `cd platform/plugins/admin/mcp && npx vitest run src/__tests__/specialist-registry.test.ts`
+Expected: PASS, 6 tests.
+
+- [ ] **Step 5: Call the module from `index.ts`**
+
+In `platform/plugins/admin/mcp/src/index.ts`, add the import beside the other local imports (near line 23):
+
+```ts
+import { classifySpecialists } from "./specialist-registry.js";
+```
+
+Replace the body of the `else` branch at lines 515-534 (everything from `const content = readFileSync(agentsMdPath, "utf-8");` to the closing brace of that `else`) with:
+
+```ts
+        const content = readFileSync(agentsMdPath, "utf-8");
+        const report = classifySpecialists({
+          agentsMd: content,
+          specialistsAgentsDir,
+          accountDir,
+          chromeUp,
+        });
+        if (report.registered === 0) {
+          checks.specialists = "not configured (AGENTS.md empty)";
+        } else {
+          checks.specialists =
+            `${report.registered} registered, missing=${report.missing} disabled=${report.disabled}\n` +
+            report.lines.join("\n");
+        }
+```
+
+- [ ] **Step 6: Build the plugin**
+
+Run: `cd platform && npm run build:admin`
+Expected: exit 0, no TypeScript errors.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add maxy-code/platform/plugins/admin/mcp/src/specialist-registry.ts maxy-code/platform/plugins/admin/mcp/src/__tests__/specialist-registry.test.ts maxy-code/platform/plugins/admin/mcp/src/index.ts
+git commit -m "$(cat <<'EOF'
+fix(2016): system-status reports a disabled agent as disabled, not missing
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+Session: a2b8f556-8297-4184-bf57-59b078a8015d
+EOF
+)"
+```
+
+---
+
+### Task 3: Disable and enable reconcile the routing prose immediately
+
+**Files:**
+- Modify: `platform/ui/server/routes/admin/agents.ts`
+- Modify: `platform/ui/server/routes/admin/__tests__/agents.test.ts`
+- Modify: `platform/plugins/docs/references/admin-ui.md:209-241`
+
+**Interfaces:**
+- Consumes: `bash <PLATFORM_ROOT>/scripts/lib/agents-md-bootstrap.sh <accountDir>` from Task 1.
+- Produces: `POST /disable` returns `{ok, moved, routingReconciled}`; `POST /enable` returns `{ok, restored, routingReconciled}`.
+
+- [ ] **Step 1: Write the failing test**
+
+In `platform/ui/server/routes/admin/__tests__/agents.test.ts`, the harness already builds a temp `platformRoot` in its `beforeEach`. Add, after the existing `templates/specialists/agents` setup in that same `beforeEach`, a copy of the real bootstrap script so the route execs shipped code rather than a stub:
+
+```ts
+  // Task 2016 — the disable path execs the real bootstrap out of PLATFORM_ROOT.
+  // Five levels up from __tests__ is maxy-code/platform, the same walk
+  // no-retired-opus-string.test.ts:18 uses.
+  mkdirSync(resolve(platformRoot, 'scripts', 'lib'), { recursive: true })
+  cpSync(
+    resolve(__dirname, '..', '..', '..', '..', '..', 'scripts', 'lib', 'agents-md-bootstrap.sh'),
+    resolve(platformRoot, 'scripts', 'lib', 'agents-md-bootstrap.sh'),
+  )
+```
+
+Add `cpSync` to the `node:fs` import list at the top of the file.
+
+Then add this case at the end of the existing `describe('disable and enable (Task 1996)', …)` block, so it reuses that block's `writeShipped`, `disable` and `enable` helpers (which already target `/api/admin/agents/<slug>/…?accountId=acct-B`):
+
+```ts
+  // Task 2016 — the routing prose has to follow the file. Before this, the
+  // append-only bootstrap kept advertising a disabled specialist and the admin
+  // dispatched to a file that was no longer there.
+  it('drops the routing line on disable and restores it on enable', async () => {
+    writeShipped('citation-auditor', { name: 'citation-auditor', description: 'Audits citations.', tools: 'Read' })
+    writeShipped('librarian', { name: 'librarian', description: 'Keeps the library.', tools: 'Read' })
+    mkdirSync(resolve(accountDir, 'agents', 'admin'), { recursive: true })
+    writeFileSync(
+      resolve(accountDir, 'agents', 'admin', 'AGENTS.md'),
+      '# Installed Roles\n\n- **specialists:citation-auditor**: Audits citations.\n- **specialists:librarian**: Keeps the library.\n',
+    )
+    const agentsMd = () => readFileSync(resolve(accountDir, 'agents', 'admin', 'AGENTS.md'), 'utf-8')
+
+    const off = await disable('citation-auditor')
+    expect(off.status).toBe(200)
+    expect(await off.json()).toMatchObject({ ok: true, moved: true, routingReconciled: true })
+    expect(agentsMd()).not.toContain('- **specialists:citation-auditor**:')
+    expect(agentsMd()).toContain('- **specialists:librarian**:')
+
+    const on = await enable('citation-auditor')
+    expect(on.status).toBe(200)
+    expect(await on.json()).toMatchObject({ ok: true, restored: true, routingReconciled: true })
+    expect(agentsMd()).toContain('- **specialists:citation-auditor**:')
+  })
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `cd platform/ui && npx vitest run server/routes/admin/__tests__/agents.test.ts -t 'routing prose'`
+Expected: FAIL — the response has no `routingReconciled` field and AGENTS.md still contains the `citation-auditor` line.
+
+- [ ] **Step 3: Implement the reconcile call**
+
+In `platform/ui/server/routes/admin/agents.ts`, add to the imports:
+
+```ts
+import { execFileSync } from 'node:child_process'
+```
+
+Add this helper immediately above the `POST /:slug/disable` handler:
+
+```ts
+/** Re-derive the admin's routing prose from disk after a disable or an enable.
+ *
+ *  `agents-md-bootstrap.sh` is the single implementation of what belongs in
+ *  AGENTS.md, so the route calls it rather than editing the file itself. It runs
+ *  after the move, so enable needs no restore path of its own: the file is live
+ *  again and the script's append loop puts the line back.
+ *
+ *  A failure here does not fail the request. The move and the store write already
+ *  happened and dispatch is already stopped, so reporting the whole disable as
+ *  failed would be false. The caller is told the truth instead, through
+ *  `routingReconciled`. */
+function reconcileRoutingProse(accountDir: string, accountId: string, op: string, slug: string): boolean {
+  const script = resolve(PLATFORM_ROOT, 'scripts', 'lib', 'agents-md-bootstrap.sh')
+  try {
+    execFileSync('bash', [script, accountDir], { encoding: 'utf-8', timeout: 10_000 })
+    return true
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    console.error(`[admin/agents] op=agents-md-reconcile source=${op} accountId=${accountId.slice(0, 8)} slug=${slug} outcome=failed reason="${msg}"`)
+    return false
+  }
+}
+```
+
+In the disable handler, replace the two closing lines (currently `console.log(… outcome=ok moved=${moved})` and `return c.json({ ok: true, moved })`) with:
+
+```ts
+  const routingReconciled = reconcileRoutingProse(resolved.accountDir, resolved.accountId, 'disable', slug)
+  console.log(`[admin/agents] op=disable accountId=${resolved.accountId.slice(0, 8)} slug=${slug} outcome=ok moved=${moved} routingReconciled=${routingReconciled}`)
+  return c.json({ ok: true, moved, routingReconciled })
+```
+
+In the enable handler, replace its two closing lines the same way:
+
+```ts
+  const routingReconciled = reconcileRoutingProse(resolved.accountDir, resolved.accountId, 'enable', slug)
+  console.log(`[admin/agents] op=enable accountId=${resolved.accountId.slice(0, 8)} slug=${slug} outcome=ok restored=${restored} routingReconciled=${routingReconciled}`)
+  return c.json({ ok: true, restored, routingReconciled })
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `cd platform/ui && npx vitest run server/routes/admin/__tests__/agents.test.ts`
+Expected: PASS, including every pre-existing case in that file.
+
+- [ ] **Step 5: Update the reference doc**
+
+In `platform/plugins/docs/references/admin-ui.md`, after the paragraph ending `a corrupt file is not evidence that an agent was disabled.` (line 224), add:
+
+```markdown
+Disabling also reconciles the admin's routing prose. `agents/admin/AGENTS.md`
+carries one `- **specialists:<name>**:` line per dispatchable specialist, and
+`agents-md-bootstrap.sh` used to only ever append, so a disabled agent stayed
+advertised and the admin dispatched to a file that was no longer there. The
+script now withholds a line for every name in the store, and both routes exec it
+after the move, so the prose is right immediately rather than after the next
+provisioning run. It emits `[agents-md] op=specialist-lines account=<id8>
+kept=<n> withheld=<comma-list|none|store-unreadable>`.
+```
+
+In the same file, replace the last sentence of the disable row (`Same \`accountId\` contract as delete.`) with:
+
+```markdown
+Returns `routingReconciled`, which is `false` when the AGENTS.md reconcile threw — the move and the store write already happened, so the request is not failed, and the caller is told rather than left assuming the prose is correct. Same `accountId` contract as delete.
+```
+
+And append to the enable row, after `404 only when neither directory nor store knows the agent.`:
+
+```markdown
+Carries the same `routingReconciled` field; the restored file is what puts the routing line back.
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add maxy-code/platform/ui/server/routes/admin/agents.ts maxy-code/platform/ui/server/routes/admin/__tests__/agents.test.ts maxy-code/platform/plugins/docs/references/admin-ui.md
+git commit -m "$(cat <<'EOF'
+fix(2016): disable and enable reconcile AGENTS.md immediately
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+Session: a2b8f556-8297-4184-bf57-59b078a8015d
+EOF
+)"
+```
+
+---
+
+### Task 4: Whole-surface verification
+
+**Files:** none modified. This task runs the checks that prove the three surfaces agree.
+
+- [ ] **Step 1: Shell suite**
+
+Run: `bash platform/scripts/__tests__/agents-md-bootstrap.test.sh`
+Expected: `FAIL=0`.
+
+- [ ] **Step 2: Admin MCP suite and type check**
+
+Run: `cd platform && npm run build:admin && cd plugins/admin/mcp && npx vitest run`
+Expected: build exit 0, every test file passes.
+
+- [ ] **Step 3: Route suite and type check**
+
+Run: `cd platform/ui && npx tsc --noEmit && npx vitest run server/routes/admin/__tests__/agents.test.ts`
+Expected: 0 type errors, all tests pass.
+
+- [ ] **Step 4: End-to-end observability check on a temp account**
+
+```bash
+ACCT=$(mktemp -d)
+mkdir -p "$ACCT/specialists/agents" "$ACCT/agents/admin"
+printf -- '---\nname: citation-auditor\ndescription: "Audits citations."\n---\n' > "$ACCT/specialists/agents/citation-auditor.md"
+printf -- '---\nname: librarian\ndescription: "Keeps the library."\n---\n' > "$ACCT/specialists/agents/librarian.md"
+bash platform/scripts/lib/agents-md-bootstrap.sh "$ACCT"
+mkdir -p "$ACCT/specialists/agents-disabled"
+mv "$ACCT/specialists/agents/citation-auditor.md" "$ACCT/specialists/agents-disabled/"
+printf '{"disabled":["citation-auditor.md"]}\n' > "$ACCT/agents-disabled.json"
+bash platform/scripts/lib/agents-md-bootstrap.sh "$ACCT"
+grep -c 'specialists:citation-auditor' "$ACCT/agents/admin/AGENTS.md" || echo "no routing line — correct"
+```
+
+Expected: the second bootstrap prints `withheld=citation-auditor kept=1`, and the grep finds no line.
+
+- [ ] **Step 5: Commit nothing**
+
+This task changes no files. If any check failed, fix it in the task that owns the file and re-run.
+
+---
+
+## Self-review
+
+- Spec section "Surface 1" → Task 1. "Surface 2" → Task 2. "Surface 3" → Task 3. "Tests" → the test steps inside Tasks 1-3 plus Task 4. "Out of scope" → nothing implemented against it.
+- Success criterion 1 (disabling removes the line) → Task 1 Step 1 case 7, Task 3 Step 1. Criterion 2 (re-enabling restores it) → Task 1 case 8, Task 3 Step 1. Criterion 3 (`system-status` separates the two) → Task 2 Step 1.
+- Names used consistently across tasks: `classifySpecialists`, `SpecialistRegistryReport`, `reconcileRoutingProse`, `routingReconciled`, `op=specialist-lines`, `op=agents-md-reconcile`.
+- No placeholders: every code step carries the code, every run step carries the command and the expected result.