@bevel-software/platform-core-backend 0.14.0 → 0.15.1

package/src/modules/settings/deployment-settings.service.ts

@@ -1,7 +1,12 @@
 import { eq, inArray } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { deploymentSettings } from '../database/core-schema.js';
-import { validateBranchModel } from '@bevel-software/platform-shared';
+import {
+  DEFAULT_KB_LAYOUT,
+  validateBranchModel,
+  validateKbLayout,
+  validateKbRootName,
+} from '@bevel-software/platform-shared';
 import { TokenCrypto } from '../../shared/token-crypto.js';
 
 /**
@@ -85,6 +90,38 @@ export const CORE_SETTINGS: SettingDef[] = [
     restartToApply: true,
   },
 
+  /**
+   * The KB layout: the three root folders a deployment may rename so hexis can
+   * read a repository laid out by someone else (`skills/` and `plugins/` in
+   * lowercase, say). Restart-to-apply like the branch model — the names are
+   * applied once at boot through `configureKbLayout` and served to the browser
+   * once by `/api/config`. Each has a default, so an unset field means the
+   * default, not an unconfigured deployment. Checked as a trio in `save`: the
+   * three must differ, and one field alone cannot see the other two.
+   */
+  {
+    key: 'knowledgeBaseDir',
+    envVar: 'KB_KNOWLEDGE_BASE_DIR',
+    section: 'knowledge-base',
+    validate: validateKbRootName,
+    restartToApply: true,
+  },
+  {
+    key: 'skillsDir',
+    envVar: 'KB_SKILLS_DIR',
+    section: 'knowledge-base',
+    validate: validateKbRootName,
+    restartToApply: true,
+  },
+  {
+    key: 'pluginsDir',
+    envVar: 'KB_PLUGINS_DIR',
+    section: 'knowledge-base',
+    validate: validateKbRootName,
+    restartToApply: true,
+  },
+
+
   /**
    * The branch model. Both are restart-to-apply and could not be otherwise:
    * the backend hands `DEFAULT_BRANCH` to services at construction, and the
@@ -109,6 +146,25 @@ export const CORE_SETTINGS: SettingDef[] = [
     restartToApply: true,
   },
 
+  {
+    /**
+     * The credential a git host's webhook or a pipeline presents to
+     * `POST /api/sync` (see `modules/kb-sync/`). Deployment-level on purpose:
+     * a person's connection key would stop the pipeline the day they leave.
+     * Optional — without it the endpoint only admits an admin's own session.
+     * Read per request, so it applies without a restart.
+     */
+    key: 'kbSyncSecret',
+    envVar: 'KB_SYNC_SECRET',
+    section: 'knowledge-base',
+    secret: true,
+    // The same floor `sync-auth.ts` enforces at request time (which is what
+    // covers a secret set through the environment); this one just says so
+    // before the save.
+    validate: (v) =>
+      v.trim().length >= 16 ? null : 'Use at least 16 characters — a random string is best.',
+  },
+
   /**
    * Single sign-on. Restart-to-apply because the provider is built once at boot
    * and pushed into the auth plugin array the server mounts from.
@@ -266,6 +322,18 @@ export class DeploymentSettingsService {
     return (this.stored.get(key) ?? '').trim();
   }
 
+  /**
+   * The KB layout in effect: each root from the environment, else the stored
+   * row, else its default. The composition root applies this once at boot.
+   */
+  resolveKbLayout(): { knowledgeBaseDir: string; skillsDir: string; pluginsDir: string } {
+    return {
+      knowledgeBaseDir: this.resolve('knowledgeBaseDir') || DEFAULT_KB_LAYOUT.knowledgeBaseDir,
+      skillsDir: this.resolve('skillsDir') || DEFAULT_KB_LAYOUT.skillsDir,
+      pluginsDir: this.resolve('pluginsDir') || DEFAULT_KB_LAYOUT.pluginsDir,
+    };
+  }
+
   /** Where {@link resolve} got its answer — what the setup screen labels the field with. */
   sourceOf(key: string): SettingSource {
     const def = this.defs.get(key);
@@ -356,11 +424,36 @@ export class DeploymentSettingsService {
       if (problem) problems.protectedBranches = problem;
     }
 
+    // The layout trio is the other cross-field rule: three names that must
+    // differ. Judged on the layout this save WOULD produce, with the default
+    // standing in for anything neither written nor stored.
+    const layoutKeys = ['knowledgeBaseDir', 'skillsDir', 'pluginsDir'] as const;
+    if (toWrite.some((w) => (layoutKeys as readonly string[]).includes(w.key))) {
+      const effective = (key: (typeof layoutKeys)[number]) =>
+        toWrite.find((w) => w.key === key)?.value || this.resolve(key) || DEFAULT_KB_LAYOUT[key];
+      const problem = validateKbLayout({
+        knowledgeBaseDir: effective('knowledgeBaseDir'),
+        skillsDir: effective('skillsDir'),
+        pluginsDir: effective('pluginsDir'),
+      });
+      // Against the field being written — the first one in the batch — since
+      // any of the three could be the one that collides.
+      if (problem) {
+        const first = toWrite.find((w) => (layoutKeys as readonly string[]).includes(w.key))!;
+        problems[first.key] = problem;
+      }
+    }
+
     if (Object.keys(problems).length > 0) throw new SettingsValidationError(problems);
 
     let restartRequired = false;
     for (const { key, value, def } of toWrite) {
-      if (def.restartToApply && this.resolve(key) !== value) restartRequired = true;
+      // Compared against the EFFECTIVE value: a layout root that was unset
+      // was already running on its default, so saving that default changes
+      // nothing a restart would pick up.
+      const effective =
+        this.resolve(key) || (DEFAULT_KB_LAYOUT as Record<string, string | undefined>)[key] || '';
+      if (def.restartToApply && effective !== value) restartRequired = true;
       const encrypted = def.secret === true;
       const stored = encrypted ? this.crypto!.encrypt(value) : value;
       await this.db

package/src/modules/settings/setup.routes.ts

@@ -16,6 +16,18 @@ import '../auth/auth.middleware.js'; // Express Request augmentation
 
 const execFileAsync = promisify(execFile);
 
+/**
+ * The slice of a sync record the status endpoint publishes. Declared here
+ * rather than imported from `kb-sync` so this module stays free of that one;
+ * the composition root hands in something that satisfies it.
+ */
+export interface LastSyncStatus {
+  at: number;
+  by: string;
+  status: 'synced' | 'partial';
+  results: Array<{ branch: string; outcome: string; error?: string }>;
+}
+
 /**
  * First-run setup — the deployment's own configuration, for the things that
  * used to be environment-only.
@@ -37,6 +49,17 @@ export function createSetupRoutes(
    * would race.
    */
   kbStartupRunner: { runAll(): Promise<void> },
+  /**
+   * The remote-sync facts the Deployment page shows beside the sync secret:
+   * the address a webhook or pipeline must call, and what the last call did.
+   * Optional so a minimal mount (tests, a distribution without the module)
+   * simply omits them from the status.
+   */
+  sync?: {
+    /** `<PUBLIC_BACKEND_URL>/api/sync` — the reader appends `/<branch>`. */
+    url: string;
+    lastSync(): LastSyncStatus | null;
+  },
 ): express.Router {
   const router = express.Router();
 
@@ -101,6 +124,7 @@ export function createSetupRoutes(
       isAdmin: true,
       settings: settings.describe(),
       ...(kbInitFailed ? { kbInitError } : {}),
+      ...(sync ? { sync: { url: sync.url, last: sync.lastSync() } } : {}),
     });
   });
 

package/src/modules/skills/__tests__/skill-access-requests.routes.test.ts

@@ -0,0 +1,128 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { DEFAULT_BRANCH, joinBranchFor } from '@bevel-software/platform-shared';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { JoinRequestsService } from '../../plugins/join-requests.service.js';
+import type { ISkillService } from '../skills.contract.js';
+import { createSkillAccessRequestRoutes } from '../skill-access-requests.routes.js';
+
+/**
+ * The branch probe behind an access request: the listing is used to PROVE a
+ * branch absent before one is cut, so it must be the strict kind — a stale
+ * list (a fetch that failed) proves nothing, and the route must stop rather
+ * than write a proposal onto a branch it never confirmed.
+ */
+
+const KB = 'knowledge-base';
+const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+const MIA = { id: 'u-mia', email: 'mia@x.io', name: 'Mia' };
+const FOLDER = 'Skills/Eng/deploy';
+
+async function makeHarness(listBranches: IWorkflowService['listBranches']) {
+  const workflow = {
+    listChangeRequestsAuthoredBy: vi.fn(async () => []),
+    listBranches: vi.fn(listBranches),
+    createBranch: vi.fn(async () => ({ name: 'x', isDefault: false, isProtected: false })),
+    commitChanges: vi.fn(async () => null),
+    openChangeRequest: vi.fn(async () => ({ number: 42 })),
+  } as unknown as IWorkflowService;
+  const workspaceService = {
+    getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: workspaceIdForBranch(branch) })),
+    readFile: vi.fn(async () => '---\n---\nwrite:\n  - Eve <eve@x.io>\n'),
+    writeFile: vi.fn(async () => undefined),
+  } as unknown as WorkspaceService;
+  const accessControl = { canWrite: vi.fn(async () => false) } as unknown as IAccessControl;
+  const skillService = {
+    listSkills: vi.fn(async () => [{ name: 'deploy', description: '', path: FOLDER }]),
+  } as unknown as ISkillService;
+
+  const app = express();
+  app.use(express.json());
+  app.use(
+    '/api',
+    createSkillAccessRequestRoutes({
+      skillService,
+      accessControl,
+      workflow,
+      workspaceService,
+      joinRequests: { list: vi.fn(), reconcile: vi.fn() } as unknown as JoinRequestsService,
+      kbDirName: KB,
+      resolveUser: async () => MIA,
+    }),
+  );
+  const server = await new Promise<Server>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const { port } = server.address() as AddressInfo;
+  return { server, url: `http://127.0.0.1:${port}/api/skills/deploy/access-request`, workflow, workspaceService };
+}
+
+describe('POST /skills/:name/access-request — the branch probe', () => {
+  let server: Server | null = null;
+  afterEach(async () => {
+    // Released here, not after the assertions: a failing assertion must not
+    // leave the console muted for every test that follows.
+    vi.restoreAllMocks();
+    if (server) await new Promise<void>((r) => server!.close(() => r()));
+    server = null;
+  });
+
+  it('proves absence with a STRICT fresh listing, then cuts the branch and opens the request', async () => {
+    const h = await makeHarness(async () => []);
+    server = h.server;
+    const res = await fetch(h.url, { method: 'POST' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, number: 42 });
+    expect(h.workflow.listBranches).toHaveBeenCalledWith(wsId, { freshFetch: true, strictFetch: true });
+    expect(h.workflow.createBranch).toHaveBeenCalledWith(wsId, joinBranchFor(MIA.email, FOLDER), DEFAULT_BRANCH);
+    // The whole chain the probe exists to enable: the grant is written AND committed.
+    expect(h.workspaceService.writeFile).toHaveBeenCalledTimes(1);
+    expect(h.workflow.commitChanges).toHaveBeenCalledTimes(1);
+  });
+
+  it('a create that loses the race proceeds once the fresh re-probe shows the branch', async () => {
+    const branch = joinBranchFor(MIA.email, FOLDER);
+    // Absent on the first probe, present on the second: someone else cut it in between.
+    let probes = 0;
+    const h = await makeHarness(async () => (probes++ === 0 ? [] : [{ name: branch, isDefault: false, isProtected: false }]));
+    (h.workflow.createBranch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('already exists'));
+    server = h.server;
+    const res = await fetch(h.url, { method: 'POST' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, number: 42 });
+    expect(h.workflow.listBranches).toHaveBeenCalledTimes(2);
+    expect(h.workspaceService.writeFile).toHaveBeenCalledTimes(1);
+    expect(h.workflow.commitChanges).toHaveBeenCalledTimes(1);
+  });
+
+  it('a create that fails with no branch to show for it stops the request — nothing is written on a branch that was not made', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const h = await makeHarness(async () => []);
+    (h.workflow.createBranch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('origin refused'));
+    server = h.server;
+    const res = await fetch(h.url, { method: 'POST' });
+    expect(res.status).toBe(500);
+    expect(h.workflow.listBranches).toHaveBeenCalledTimes(2);
+    expect(h.workspaceService.writeFile).not.toHaveBeenCalled();
+    expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('a listing that could not prove anything stops the request before a branch or a byte is written', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const h = await makeHarness(async () => {
+      throw new Error('the fetch from origin failed, so the branch list cannot prove absence');
+    });
+    server = h.server;
+    const res = await fetch(h.url, { method: 'POST' });
+    expect(res.status).toBe(500);
+    expect(h.workflow.createBranch).not.toHaveBeenCalled();
+    expect(h.workspaceService.writeFile).not.toHaveBeenCalled();
+    expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
+  });
+});

package/src/modules/skills/__tests__/skills.service.test.ts

@@ -67,6 +67,62 @@ describe('SkillService', () => {
   });
   afterEach(() => rm(root, { recursive: true, force: true }));
 
+  test('lists shared skills under the Skills root alongside plugin skills', async () => {
+    const shared = join(root, wsId, KB_DIR, 'Skills', 'Engineering', 'deploy');
+    await mkdir(shared, { recursive: true });
+    await writeFile(join(shared, 'SKILL.md'), '---\ndescription: Ship it.\n---\n\n# Deploy\n');
+    // A skill directly under the root, no scope folder — also a skill.
+    const bare = join(root, wsId, KB_DIR, 'Skills', 'triage');
+    await mkdir(bare, { recursive: true });
+    await writeFile(join(bare, 'SKILL.md'), '---\ndescription: Triage.\n---\n');
+
+    const list = await svc().listSkills();
+    expect(list.find((s) => s.name === 'deploy')?.path).toBe('Skills/Engineering/deploy');
+    expect(list.find((s) => s.name === 'triage')?.path).toBe('Skills/triage');
+    // The plugin tree is still scanned: the union is the catalog.
+    expect(list.find((s) => s.name === 'rfi')?.path).toBe('Plugins/rfi');
+
+    const res = await svc().getSkill('u@x.io', 'deploy');
+    expect(res.ok && res.kind === 'skill' && res.skill.body).toContain('# Deploy');
+  });
+
+  test('honours a .bevelignore inside a root, so a build output never shadows the source', async () => {
+    // A repository that commits a compiled copy of every skill beside the
+    // source: without the ignore, `dist/…/rfi` would collide with `Plugins/rfi`.
+    const dist = join(root, wsId, KB_DIR, 'Skills', 'dist', 'rfi');
+    await mkdir(dist, { recursive: true });
+    await writeFile(join(dist, 'SKILL.md'), '---\ndescription: compiled copy\n---\n');
+    await writeFile(join(root, wsId, KB_DIR, 'Skills', '.bevelignore'), 'dist/\n');
+
+    const list = await svc().listSkills();
+    expect(list.filter((s) => s.name === 'rfi').map((s) => s.path)).toEqual(['Plugins/rfi']);
+    expect(list.some((s) => s.path.includes('/dist/'))).toBe(false);
+  });
+
+  test('ignores the repo-root .bevelignore: hiding a root from the file tree must not empty the catalog', async () => {
+    // The seeded template hides `Plugins/` (and `Skills/`) from the Knowledge
+    // tree with exactly this file. The catalog is what those roots exist for.
+    await writeFile(join(root, wsId, KB_DIR, '.bevelignore'), 'Plugins/\nSkills/\n');
+    const shared = join(root, wsId, KB_DIR, 'Skills', 'deploy');
+    await mkdir(shared, { recursive: true });
+    await writeFile(join(shared, 'SKILL.md'), '---\ndescription: Ship it.\n---\n');
+
+    const list = await svc().listSkills();
+    expect(list.map((s) => s.name).sort()).toEqual(['coding-guidelines', 'deploy', 'rfi']);
+  });
+
+  test('a nested .bevelignore applies beneath the folder that carries it', async () => {
+    const scope = join(root, wsId, KB_DIR, 'Skills', 'Sales');
+    await mkdir(join(scope, 'drafts', 'pitch'), { recursive: true });
+    await mkdir(join(scope, 'pitch'), { recursive: true });
+    await writeFile(join(scope, 'drafts', 'pitch', 'SKILL.md'), '---\ndescription: draft\n---\n');
+    await writeFile(join(scope, 'pitch', 'SKILL.md'), '---\ndescription: released\n---\n');
+    await writeFile(join(scope, '.bevelignore'), 'drafts/\n');
+
+    const list = await svc().listSkills();
+    expect(list.filter((s) => s.name === 'pitch').map((s) => s.path)).toEqual(['Skills/Sales/pitch']);
+  });
+
   test('lists skills with a block-scalar description parsed correctly', async () => {
     const skills = await svc().listSkills();
     expect(skills).toHaveLength(2);
@@ -145,6 +201,35 @@ describe('SkillService', () => {
     expect(trav).toEqual({ ok: false, error: 'invalid_file' });
   });
 
+  test('an ignored SKILL.md suppresses the skill and NEVER promotes its assets to skills', async () => {
+    const rfi = join(root, wsId, KB_DIR, 'Plugins', 'rfi');
+    await writeFile(join(rfi, '.bevelignore'), 'SKILL.md\n');
+    await mkdir(join(rfi, 'examples'), { recursive: true });
+    await writeFile(join(rfi, 'examples', 'SKILL.md'), '---\ndescription: An example, not a skill.\n---\n');
+    const names = (await svc().listSkills()).map((s) => s.name);
+    expect(names).not.toContain('rfi');
+    expect(names).not.toContain('examples');
+  });
+
+  test('ignore rules reach a skill\'s bundled files: hidden from the listing and refused when asked for', async () => {
+    const rfi = join(root, wsId, KB_DIR, 'Plugins', 'rfi');
+    await writeFile(join(rfi, '.bevelignore'), 'scripts/\n');
+    const res = await svc().getSkill('user@x.eu', 'rfi');
+    expect(res.ok && res.kind === 'skill' ? res.skill.files : null).toEqual([]);
+    expect(await svc().getSkill('user@x.eu', 'rfi', 'scripts/build_xlsx.py')).toEqual({
+      ok: false,
+      error: 'not_found',
+    });
+  });
+
+  test('a skill that exists inline AND under the shared root resolves to the shared copy', async () => {
+    const shared = join(root, wsId, KB_DIR, 'Skills', 'Ops', 'rfi');
+    await mkdir(shared, { recursive: true });
+    await writeFile(join(shared, 'SKILL.md'), '---\ndescription: The canonical one.\n---\n');
+    const rfi = (await svc().listSkills()).find((s) => s.name === 'rfi');
+    expect(rfi?.path).toBe('Skills/Ops/rfi');
+  });
+
   test('listSkills filters by canRead for a given user', async () => {
     const denyRfi: IAccessControl = {
       canRead: async () => false,

package/src/modules/skills/index.ts

@@ -2,6 +2,7 @@ export { SkillService } from './skills.service.js';
 export { PendingSkillsService } from './pending-skills.service.js';
 export { registerSkillsTools } from './skills.tools.js';
 export { createSkillsRoutes } from './skills.routes.js';
+export { createSkillAccessRequestRoutes } from './skill-access-requests.routes.js';
 export type {
   ISkillService,
   IPendingSkillService,

package/src/modules/skills/pending-skills.service.ts

@@ -1,6 +1,7 @@
 import {
   DEFAULT_BRANCH,
   PLUGINS_DIR,
+  SKILLS_DIR,
   type ChangeRequest,
   type IWorkflowService,
 } from '@bevel-software/platform-shared';
@@ -118,6 +119,8 @@ export class PendingSkillsService implements IPendingSkillService {
         name: isSafeSkillName(declared) ? declared : folderName,
         description: fm.description,
         version: fm.version,
+        owner: fm.owner,
+        lifecycle: fm.lifecycle,
         path: folder,
         changeRequestNumber: cr.number,
         branch: cr.branch,
@@ -156,11 +159,10 @@ export class PendingSkillsService implements IPendingSkillService {
  */
 function isSkillDoc(repoRelPath: string): boolean {
   const segments = repoRelPath.split('/');
-  return (
-    segments.length >= 4 &&
-    segments[0] === PLUGINS_DIR &&
-    segments[segments.length - 1] === SKILL_DOC
-  );
+  if (segments[segments.length - 1] !== SKILL_DOC) return false;
+  // Under `Skills/` a skill may sit directly below the root: `Skills/<skill>/SKILL.md`.
+  if (segments[0] === SKILLS_DIR) return segments.length >= 3;
+  return segments.length >= 4 && segments[0] === PLUGINS_DIR;
 }
 
 /** The skill folder holding a SKILL.md. */

package/src/modules/skills/skill-access-requests.routes.ts

@@ -0,0 +1,199 @@
+import express from 'express';
+import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import {
+  DEFAULT_BRANCH,
+  joinBranchFor,
+  type AuthUser,
+  type IWorkflowService,
+} from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { spliceGrant } from '../access-model/access-splice.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { JoinRequestsService } from '../plugins/join-requests.service.js';
+import type { ISkillService } from './skills.contract.js';
+
+/**
+ * Asking for WRITE on a shared skill — the same machinery as asking to join a
+ * plugin, pointed at a skill folder instead of a plugin folder.
+ *
+ *   POST /api/skills/:name/access-request               → { ok, number }
+ *   GET  /api/skills/:name/access-requests              → { requests }   (skill editors)
+ *   POST /api/skills/:name/access-requests/:n/reconcile → { closed }
+ *
+ * Why it exists: linking a skill into a plugin needs write on the skill's
+ * rules (the link grants the plugin's principal there), and a plugin manager
+ * often has no say over a skill some other scope owns. The request is a plain
+ * change request whose branch splices `write: <requester>` into the skill
+ * folder's `access.md`; the skill's editors see its proposals and accept
+ * through the ordinary grant path, and it retires itself once the default
+ * branch carries the grant (`JoinRequestsService`, keyed on the skill FOLDER
+ * path rather than a plugin name — the branch-name convention takes any
+ * exact string).
+ *
+ * Fail-closed like the skill catalog: a skill the caller cannot read answers
+ * as unknown, and the editors' listing answers `[]` to anyone else.
+ */
+export function createSkillAccessRequestRoutes(deps: {
+  skillService: ISkillService;
+  accessControl: IAccessControl;
+  workflow: IWorkflowService;
+  workspaceService: WorkspaceService;
+  joinRequests: JoinRequestsService;
+  kbDirName: string;
+  resolveUser: (req: express.Request) => Promise<AuthUser | null>;
+}): express.Router {
+  const { skillService, accessControl, workflow, workspaceService, joinRequests, kbDirName, resolveUser } = deps;
+  const router = express.Router();
+  const wsId = () => workspaceIdForBranch(DEFAULT_BRANCH);
+  const rulesOf = (folder: string) => `${folder}/access.md`;
+
+  /** The skill the caller may read, by name — or null after answering 404. */
+  async function readableSkill(
+    req: express.Request,
+    res: express.Response,
+  ): Promise<{ user: AuthUser; folder: string; name: string } | null> {
+    const user = await resolveUser(req);
+    if (!user) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return null;
+    }
+    const name = String(req.params.name);
+    const skill = (await skillService.listSkills(user.email)).find((s) => s.name === name);
+    if (!skill) {
+      res.status(404).json({ error: 'Unknown skill', kind: 'unknown-skill' });
+      return null;
+    }
+    return { user, folder: skill.path, name };
+  }
+
+  router.post('/skills/:name/access-request', async (req, res) => {
+    try {
+      const ctx = await readableSkill(req, res);
+      if (!ctx) return;
+      const { user, folder, name } = ctx;
+      if (await accessControl.canWrite(wsId(), user.email, rulesOf(folder))) {
+        res.status(409).json({ error: 'You can already edit this skill', kind: 'already-writable' });
+        return;
+      }
+      const branch = joinBranchFor(user.email, folder);
+      // FRESH: a repeated click must find the request the previous one opened,
+      // and the cached listing can trail it — a miss here would send the
+      // retry into a duplicate refusal.
+      const existing = (await workflow.listChangeRequestsAuthoredBy(user.email, { fresh: true })).find(
+        (cr) => cr.state === 'open' && cr.branch === branch,
+      );
+      if (existing) {
+        res.json({ ok: true, number: existing.number });
+        return;
+      }
+      // The branch may already exist (a request listed as closed, a retry
+      // after a failed open). Existence is PROBED, before and — if creation
+      // fails — after: the race shows up as "already exists" locally or as a
+      // rejected push when origin got there first, and a message is not a
+      // contract. A branch that is there is proceeded against; anything else
+      // is a real failure, and a proposal on a branch that was not made would
+      // be worse than the error. STRICT: the list proves absence, and a
+      // listing that could not fetch proves nothing — it throws instead of
+      // serving refs from before the branch was made (or deleted).
+      const branchExists = async () =>
+        (await workflow.listBranches(wsId(), { freshFetch: true, strictFetch: true })).some(
+          (b) => b.name === branch,
+        );
+      if (!(await branchExists())) {
+        try {
+          await workflow.createBranch(wsId(), branch, DEFAULT_BRANCH);
+        } catch (err) {
+          if (!(await branchExists())) throw err;
+        }
+      }
+      const ws = await workspaceService.getOrCreateForBranch(branch);
+      const accessPath = `${kbDirName}/${rulesOf(folder)}`;
+      // Only a PROVEN absence reads as "no rules yet": any other failure must
+      // not be turned into an empty file that a splice then overwrites.
+      const current = await workspaceService.readFile(ws.id, accessPath).catch((err: unknown) => {
+        const code = (err as { code?: unknown } | null)?.code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR') throw err;
+        return '';
+      });
+      const spliced = spliceGrant(
+        current,
+        'write',
+        { kind: 'user', email: user.email, displayName: user.name },
+        { target: 'folder' },
+      );
+      if (spliced.changed) {
+        await workspaceService.writeFile(ws.id, accessPath, spliced.text);
+        await workflow.commitChanges(ws.id, user, `Request write access to ${name}`);
+      }
+      const detail = await workflow.openChangeRequest(ws.id, user, {
+        sourceBranch: branch,
+        targetBranch: DEFAULT_BRANCH,
+        title: `Access request: ${name}`,
+        description:
+          `${user.name} asked to edit the skill ${name}. An editor of the skill accepts by ` +
+          `granting the access this branch proposes; the request closes itself once ` +
+          `every proposal has landed.`,
+      });
+      res.json({ ok: true, number: detail.number });
+    } catch (err) {
+      if (err instanceof WorkflowDomainError) {
+        res.status(err.status).json({ error: err.message, ...(err.payload ?? {}) });
+        return;
+      }
+      console.error('[skills] failed to open an access request:', err);
+      res.status(500).json({ error: 'Failed to request access' });
+    }
+  });
+
+  /** The caller as an EDITOR of the skill's rules, or null after answering. */
+  async function requireEditor(
+    req: express.Request,
+    res: express.Response,
+    onDenied: () => void,
+  ): Promise<{ user: AuthUser; folder: string } | null> {
+    const ctx = await readableSkill(req, res);
+    if (!ctx) return null;
+    if (!(await accessControl.canWrite(wsId(), ctx.user.email, rulesOf(ctx.folder)))) {
+      onDenied();
+      return null;
+    }
+    return ctx;
+  }
+
+  router.get('/skills/:name/access-requests', async (req, res) => {
+    try {
+      const ctx = await requireEditor(req, res, () => res.json({ requests: [] }));
+      if (!ctx) return;
+      const crs = await workflow.listChangeRequests();
+      res.json({ requests: await joinRequests.list(ctx.folder, ctx.folder, crs, ctx.user) });
+    } catch (err) {
+      console.error('[skills] failed to list access requests:', err);
+      res.status(500).json({ error: 'Failed to list access requests' });
+    }
+  });
+
+  router.post('/skills/:name/access-requests/:number/reconcile', async (req, res) => {
+    try {
+      const ctx = await requireEditor(req, res, () => res.status(404).json({ error: 'Not found' }));
+      if (!ctx) return;
+      const crNumber = Number(req.params.number);
+      if (!Number.isSafeInteger(crNumber) || crNumber <= 0) {
+        res.status(400).json({ error: 'Invalid change request number' });
+        return;
+      }
+      const cr = await workflow.getChangeRequest(crNumber);
+      if (!cr) {
+        res.status(404).json({ error: 'Not found' });
+        return;
+      }
+      res.json({ closed: await joinRequests.reconcile(ctx.folder, ctx.folder, cr, ctx.user) });
+    } catch (err) {
+      console.error('[skills] failed to reconcile an access request:', err);
+      res.status(500).json({ error: 'Failed to reconcile the request' });
+    }
+  });
+
+  return router;
+}