@celilo/cli 0.11.0 → 0.12.1

package/src/module/packaging/workspace-deps.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Packager resolves `workspace:` build deps in an isolated staging dir by
+ * rewriting them to `file:` paths pointing at the live monorepo member
+ * (ISS-0147 / celilo#216).
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { rewriteWorkspaceDeps } from './workspace-deps';
+
+describe('rewriteWorkspaceDeps', () => {
+  let repo: string; // fake monorepo root
+  let sourceDir: string; // module source under the monorepo
+  let buildDir: string; // isolated staging copy
+
+  function write(base: string, rel: string, obj: unknown): void {
+    const full = join(base, rel);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, typeof obj === 'string' ? obj : JSON.stringify(obj, null, 2));
+  }
+
+  beforeEach(() => {
+    repo = mkdtempSync(join(tmpdir(), 'celilo-ws-repo-'));
+    // Monorepo root with workspace globs mirroring the real repo.
+    write(repo, 'package.json', {
+      name: 'infra',
+      private: true,
+      workspaces: ['packages/*', 'modules/*/site'],
+    });
+    // A sibling workspace package.
+    write(repo, 'packages/visualizer/package.json', {
+      name: '@celilo/visualizer',
+      version: '0.1.0',
+    });
+    sourceDir = join(repo, 'modules/website');
+    mkdirSync(sourceDir, { recursive: true });
+
+    // Isolated staging copy of the module (what the packager builds in).
+    buildDir = mkdtempSync(join(tmpdir(), 'celilo-ws-stage-'));
+    write(buildDir, 'site/package.json', {
+      name: 'website',
+      dependencies: { '@celilo/visualizer': 'workspace:^', astro: '^5.7.0' },
+    });
+  });
+
+  afterEach(() => {
+    for (const d of [repo, buildDir]) {
+      try {
+        rmSync(d, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+    }
+  });
+
+  it('rewrites a workspace: spec to a file: path at the live member', () => {
+    const rewrites = rewriteWorkspaceDeps(buildDir, sourceDir);
+
+    const pkg = JSON.parse(readFileSync(join(buildDir, 'site/package.json'), 'utf-8'));
+    expect(pkg.dependencies['@celilo/visualizer']).toBe(
+      `file:${join(repo, 'packages/visualizer')}`,
+    );
+    // Non-workspace deps untouched.
+    expect(pkg.dependencies.astro).toBe('^5.7.0');
+    expect(rewrites).toHaveLength(1);
+  });
+
+  it('is a no-op when there are no workspace deps', () => {
+    write(buildDir, 'site/package.json', {
+      name: 'website',
+      dependencies: { astro: '^5.7.0' },
+    });
+    expect(rewriteWorkspaceDeps(buildDir, sourceDir)).toEqual([]);
+  });
+
+  it('fails loudly naming an unresolvable workspace dep', () => {
+    write(buildDir, 'site/package.json', {
+      name: 'website',
+      dependencies: { '@celilo/ghost': 'workspace:*' },
+    });
+    expect(() => rewriteWorkspaceDeps(buildDir, sourceDir)).toThrow(/@celilo\/ghost/);
+  });
+
+  it('handles the workspaces:{packages:[]} object form', () => {
+    write(repo, 'package.json', {
+      name: 'infra',
+      workspaces: { packages: ['packages/*', 'modules/*/site'] },
+    });
+    const rewrites = rewriteWorkspaceDeps(buildDir, sourceDir);
+    expect(rewrites).toHaveLength(1);
+  });
+});

package/src/module/packaging/workspace-deps.ts

@@ -0,0 +1,185 @@
+/**
+ * Resolve bun `workspace:` protocol build deps in an isolated staging build
+ * (ISS-0147 / celilo#216).
+ *
+ * `celilo package <module>` stages the module into an isolated temp dir and
+ * runs the manifest `build:` there. A module whose build depends on a sibling
+ * monorepo package via `workspace:` (e.g. celilo-website's site/package.json
+ * `@celilo/visualizer: workspace:^`) then fails: the staging dir has no
+ * workspace root, so `bun install` errors with "Workspace dependency not
+ * found".
+ *
+ * Fix: before the staged build runs, rewrite every `workspace:` spec in the
+ * staged package.json files to a `file:<abs path>` pointing at the live
+ * monorepo member. bun installs local path deps from the current source — so
+ * the bundle reflects the CURRENT workspace version, never a stale published
+ * one (unlike an npm pin). No hand-rolled CELILO_MODULE_SOURCE_DIR dance.
+ */
+
+import { type Dirent, existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+const DEP_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+] as const;
+
+interface WorkspaceInfo {
+  root: string;
+  /** package name -> absolute member directory */
+  members: Map<string, string>;
+}
+
+/**
+ * Walk up from `startDir` to find the monorepo root — the nearest ancestor
+ * package.json declaring a `workspaces` field — and map every member package
+ * name to its absolute directory. Returns null if no workspace root exists.
+ */
+function findWorkspaceRoot(startDir: string): WorkspaceInfo | null {
+  let dir = resolve(startDir);
+  for (;;) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      const patterns = readWorkspacePatterns(pkgPath);
+      if (patterns) {
+        return { root: dir, members: collectMembers(dir, patterns) };
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function readWorkspacePatterns(pkgPath: string): string[] | null {
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    // npm/bun accept both `workspaces: [...]` and `workspaces: { packages: [...] }`.
+    if (Array.isArray(pkg.workspaces)) return pkg.workspaces;
+    if (Array.isArray(pkg.workspaces?.packages)) return pkg.workspaces.packages;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function collectMembers(root: string, patterns: string[]): Map<string, string> {
+  const members = new Map<string, string>();
+  for (const pattern of patterns) {
+    for (const memberDir of expandGlob(root, pattern)) {
+      const pkgPath = join(memberDir, 'package.json');
+      if (!existsSync(pkgPath)) continue;
+      try {
+        const name = JSON.parse(readFileSync(pkgPath, 'utf-8')).name;
+        if (typeof name === 'string' && name.length > 0) members.set(name, memberDir);
+      } catch {
+        /* member without a valid package.json — skip */
+      }
+    }
+  }
+  return members;
+}
+
+/**
+ * Expand a workspace glob against `root`. Supports only the single `*`
+ * per-segment wildcard bun/npm workspace patterns actually use (e.g.
+ * "packages/[star]" or "modules/[star]/site"). ponytail: no globstar/brace
+ * support — no workspace config uses them; add if one ever does.
+ */
+function expandGlob(root: string, pattern: string): string[] {
+  let dirs = [root];
+  for (const segment of pattern.split('/')) {
+    const next: string[] = [];
+    for (const dir of dirs) {
+      if (segment === '*') {
+        let entries: Dirent[];
+        try {
+          entries = readdirSync(dir, { withFileTypes: true });
+        } catch {
+          continue;
+        }
+        for (const entry of entries) {
+          if (entry.isDirectory()) next.push(join(dir, entry.name));
+        }
+      } else {
+        const candidate = join(dir, segment);
+        if (existsSync(candidate)) next.push(candidate);
+      }
+    }
+    dirs = next;
+  }
+  return dirs;
+}
+
+function findPackageJsonFiles(dir: string): string[] {
+  const found: string[] = [];
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      found.push(...findPackageJsonFiles(full));
+    } else if (entry.name === 'package.json') {
+      found.push(full);
+    }
+  }
+  return found;
+}
+
+/**
+ * Rewrite every `workspace:` dep in the staged build dir's package.json files
+ * to a `file:` path pointing at the live monorepo member.
+ *
+ * @param buildDir - isolated staging dir being built
+ * @param sourceDir - original (unstaged) module dir, used to locate the monorepo root
+ * @returns human-readable list of rewrites performed (for logging)
+ * @throws if a `workspace:` dep can't be resolved to a monorepo member —
+ *   loud failure naming the offending dep, never a cryptic downstream error.
+ */
+export function rewriteWorkspaceDeps(buildDir: string, sourceDir: string): string[] {
+  const rewrites: string[] = [];
+  let workspace: WorkspaceInfo | null | undefined;
+
+  for (const pkgPath of findPackageJsonFiles(buildDir)) {
+    let pkg: Record<string, unknown>;
+    try {
+      pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    } catch {
+      continue;
+    }
+
+    let changed = false;
+    for (const field of DEP_FIELDS) {
+      const deps = pkg[field];
+      if (!deps || typeof deps !== 'object') continue;
+      for (const [name, spec] of Object.entries(deps as Record<string, unknown>)) {
+        if (typeof spec !== 'string' || !spec.startsWith('workspace:')) continue;
+
+        // Lazily locate the workspace root only once a workspace dep exists.
+        if (workspace === undefined) workspace = findWorkspaceRoot(sourceDir);
+        const memberDir = workspace?.members.get(name);
+        if (!memberDir) {
+          throw new Error(
+            `Module build depends on workspace package "${name}" (${field}: "${spec}"), ` +
+              `but it could not be resolved to a monorepo member from ${sourceDir}.\n` +
+              `Ensure "${name}" is a workspace member, or replace the "workspace:" spec with a published version range.`,
+          );
+        }
+        (deps as Record<string, string>)[name] = `file:${memberDir}`;
+        rewrites.push(`${name}: ${spec} -> file:${memberDir}`);
+        changed = true;
+      }
+    }
+
+    if (changed) writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+  }
+
+  return rewrites;
+}

package/src/module/versioning/changeset-version.ts

@@ -1,5 +1,5 @@
 /**
- * Changeset-driven module versioning (ISS-0151 / v2/MODULE_VERSIONING.md).
+ * Changeset-driven module versioning (ISS-0151 / openspec/changes/module-version-semantics/proposal.md).
  *
  * For `version_source: { kind: changeset }` modules, the payload version is
  * authored via `.changeset/*.md` files — the same on-disk format the changesets

package/src/policy/no-hand-built-ssh.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Recurrence gate for openspec/changes/unified-management-no-ssh/proposal.md: **modules never hand-build SSH.**
+ *
+ * Module hooks reach a remote box through the typed primitives in
+ * `@celilo/capabilities` (probe / serviceCtl / applyRenderedConfig / … — see
+ * apps/celilo/MODULE_PRIMITIVES.md), never a raw `ssh root@…` string, `ssh2`, or
+ * an ad-hoc `child_process` shell-out. This test scans every production module
+ * script and fails if a banned pattern reappears, so the SSH-elimination work
+ * can't silently erode.
+ *
+ * Precise on purpose: `noRestrictedImports` can't see raw ssh *strings* (the real
+ * risk). We ban the SSH shapes themselves — an `ssh root@…` string catches
+ * hand-built SSH however it's invoked (child_process, execSync, or the Runner),
+ * and `ssh2` catches the library route. We do NOT ban `child_process` outright:
+ * many modules' on_install legitimately shell LOCAL `celilo`/system commands
+ * (`celilo system apply-config`), which isn't remote SSH.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+/** Walk up from this test to the repo root (the dir holding both modules/ and apps/). */
+function repoRoot(): string {
+  let dir = import.meta.dir;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'modules')) && existsSync(join(dir, 'apps'))) return dir;
+    dir = resolve(dir, '..');
+  }
+  throw new Error('could not locate repo root (no ancestor with modules/ + apps/)');
+}
+
+/** Every production `.ts` under modules/<m>/scripts/ (excludes node_modules + tests). */
+function moduleScripts(): string[] {
+  const modulesRoot = join(repoRoot(), 'modules');
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir)) {
+      if (entry === 'node_modules') continue;
+      const p = join(dir, entry);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (p.endsWith('.ts') && !p.endsWith('.test.ts')) out.push(p);
+    }
+  };
+  for (const mod of readdirSync(modulesRoot)) {
+    const scripts = join(modulesRoot, mod, 'scripts');
+    if (existsSync(scripts) && statSync(scripts).isDirectory()) walk(scripts);
+  }
+  return out;
+}
+
+const BANNED = [
+  {
+    name: 'raw ssh invocation (StrictHostKeyChecking)',
+    re: /StrictHostKeyChecking/,
+    hint: 'Use a remote-ops primitive (remoteExec/probe/serviceCtl/…). See MODULE_PRIMITIVES.md.',
+  },
+  {
+    name: 'raw ssh invocation (ssh … root@)',
+    re: /\bssh\s+(?:-\S+\s+|\S*root@)/,
+    hint: 'Use a remote-ops primitive, not a hand-built ssh string. See MODULE_PRIMITIVES.md.',
+  },
+  {
+    name: "'ssh2' import",
+    re: /(?:from|require\()\s*['"]ssh2['"]/,
+    hint: 'Modules never open their own SSH connection — use the primitives. See MODULE_PRIMITIVES.md.',
+  },
+];
+
+describe('recurrence gate: modules never hand-build SSH', () => {
+  const scripts = moduleScripts();
+
+  test('scans a non-trivial set of module scripts (sanity — the scan actually ran)', () => {
+    expect(scripts.length).toBeGreaterThan(10);
+  });
+
+  test('no production module script hand-builds SSH (ssh string / ssh2)', () => {
+    const violations: string[] = [];
+    for (const file of scripts) {
+      const src = readFileSync(file, 'utf-8');
+      for (const b of BANNED) {
+        if (b.re.test(src)) violations.push(`${file}\n    → ${b.name}. ${b.hint}`);
+      }
+    }
+    expect(
+      violations,
+      `Hand-built SSH found in module scripts:\n  ${violations.join('\n  ')}`,
+    ).toEqual([]);
+  });
+});

package/src/registry/client.test.ts

@@ -226,3 +226,89 @@ describe('RegistryClient.publish — Cargo binary protocol', () => {
     ).rejects.toThrow('token invalid');
   });
 });
+
+// ── module-owner admin endpoints (ce-1ch) ─────────────────────────────────────
+
+describe('RegistryClient owner methods', () => {
+  let fetchSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = spyOn(globalThis, 'fetch');
+  });
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  test('listOwners GETs /owners with the admin token and returns the array', async () => {
+    const owners = [
+      {
+        moduleName: 'homebridge',
+        ownerSub: 'alice',
+        claimedAt: 'T',
+        sourceGroup: 'celilo-authors',
+      },
+    ];
+    fetchSpy.mockResolvedValue(new Response(JSON.stringify({ owners }), { status: 200 }));
+    const client = new RegistryClient('https://reg.example.com');
+    const result = await client.listOwners('admin-tok');
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe('https://reg.example.com/api/v1/modules/owners');
+    expect((init.headers as Record<string, string>).Authorization).toBe('admin-tok');
+    expect(result).toEqual(owners);
+  });
+
+  test('listOwners throws the server error detail on failure', async () => {
+    fetchSpy.mockResolvedValue(
+      new Response(JSON.stringify({ errors: [{ detail: 'Unauthorized' }] }), { status: 401 }),
+    );
+    const client = new RegistryClient('https://reg.example.com');
+    await expect(client.listOwners('nope')).rejects.toThrow('Unauthorized');
+  });
+
+  test('getOwner returns null on 404 (unclaimed)', async () => {
+    fetchSpy.mockResolvedValue(new Response(null, { status: 404 }));
+    const client = new RegistryClient('https://reg.example.com');
+    expect(await client.getOwner('never-claimed', 'admin-tok')).toBeNull();
+  });
+
+  test('getOwner returns the owner entry on 200', async () => {
+    const owner = {
+      moduleName: 'caddy',
+      ownerSub: 'bob',
+      claimedAt: 'T',
+      sourceGroup: 'celilo-admins',
+    };
+    fetchSpy.mockResolvedValue(new Response(JSON.stringify({ owner }), { status: 200 }));
+    const client = new RegistryClient('https://reg.example.com');
+    expect(await client.getOwner('caddy', 'admin-tok')).toEqual(owner);
+  });
+
+  test('setOwner POSTs ownerSub and returns the updated entry', async () => {
+    const owner = {
+      moduleName: 'homebridge',
+      ownerSub: 'carol',
+      claimedAt: 'T',
+      sourceGroup: 'admin-reassign',
+    };
+    fetchSpy.mockResolvedValue(new Response(JSON.stringify({ ok: true, owner }), { status: 200 }));
+    const client = new RegistryClient('https://reg.example.com');
+    const result = await client.setOwner('homebridge', 'carol', 'admin-tok');
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe('https://reg.example.com/api/v1/modules/owners/homebridge');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body as string)).toEqual({ ownerSub: 'carol' });
+    expect(result).toEqual(owner);
+  });
+
+  test('setOwner throws the server error detail on failure', async () => {
+    fetchSpy.mockResolvedValue(
+      new Response(JSON.stringify({ errors: [{ detail: 'ownerSub is required' }] }), {
+        status: 400,
+      }),
+    );
+    const client = new RegistryClient('https://reg.example.com');
+    await expect(client.setOwner('homebridge', '', 'admin-tok')).rejects.toThrow(
+      'ownerSub is required',
+    );
+  });
+});

package/src/registry/client.ts

@@ -40,6 +40,14 @@ export interface ModuleMetadata {
   versions: Array<{ num: string; yanked: boolean; created_at: string }>;
 }
 
+/** A module-owner table entry (ce-1ch). Mirrors the registry-server shape. */
+export interface ModuleOwner {
+  moduleName: string;
+  ownerSub: string;
+  claimedAt: string;
+  sourceGroup: string;
+}
+
 export class RegistryClient {
   readonly baseUrl: string;
 
@@ -158,10 +166,68 @@ export class RegistryClient {
     return resp.json() as Promise<{ ok: boolean; name: string; vers: string }>;
   }
 
+  // ── Module ownership (admin — ce-1ch) ──────────────────────────────────────
+
+  /** List the whole module-owner table. Requires an admin token. */
+  async listOwners(token: string): Promise<ModuleOwner[]> {
+    const resp = await this.authed(`${this.baseUrl}/api/v1/modules/owners`, token);
+    const body = (await resp.json()) as { owners: ModuleOwner[] };
+    return body.owners;
+  }
+
+  /** Show the owner of one module name, or null if unclaimed. Requires an admin token. */
+  async getOwner(name: string, token: string): Promise<ModuleOwner | null> {
+    const url = `${this.baseUrl}/api/v1/modules/owners/${encodeURIComponent(name)}`;
+    const resp = await fetch(url, {
+      headers: { Authorization: token },
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (resp.status === 404) return null;
+    if (!resp.ok) throw new Error(await this.errorDetail(resp));
+    const body = (await resp.json()) as { owner: ModuleOwner };
+    return body.owner;
+  }
+
+  /** Reassign a module name to `ownerSub` (admin overwrite). Requires an admin token. */
+  async setOwner(name: string, ownerSub: string, token: string): Promise<ModuleOwner> {
+    const url = `${this.baseUrl}/api/v1/modules/owners/${encodeURIComponent(name)}`;
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: { Authorization: token, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ownerSub }),
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (!resp.ok) throw new Error(await this.errorDetail(resp));
+    const body = (await resp.json()) as { owner: ModuleOwner };
+    return body.owner;
+  }
+
   // ── Internal ──────────────────────────────────────────────────────────────
 
+  /** GET with an Authorization header, throwing the server's error detail on failure. */
+  private async authed(url: string, token: string): Promise<Response> {
+    const resp = await fetch(url, {
+      headers: { Authorization: token },
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (!resp.ok) throw new Error(await this.errorDetail(resp));
+    return resp;
+  }
+
+  /** Extract `errors[0].detail` from a Cargo-protocol error body, or fall back to the status. */
+  private async errorDetail(resp: Response): Promise<string> {
+    const body = (await resp.json().catch(() => ({}))) as {
+      errors?: Array<{ detail: string }>;
+    };
+    return body.errors?.[0]?.detail ?? `HTTP ${resp.status}`;
+  }
+
   private async get(url: string): Promise<Response> {
-    const resp = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+    // 30s (was 15s): a module .netapp can be tens of MB and the download must
+    // finish within one window. 15s was too aggressive on slow links — the
+    // download of a ~19MB module over a multi-hop path (e2e sim NAT, real WAN)
+    // intermittently timed out mid-transfer.
+    const resp = await fetch(url, { signal: AbortSignal.timeout(30_000) });
     if (!resp.ok) {
       throw new Error(`Registry error at ${url}: HTTP ${resp.status}`);
     }

package/src/services/api-access.ts

@@ -1,5 +1,5 @@
 /**
- * Remote API access control (see v2/API_COMMUNICATION.md, Slice 2a).
+ * Remote API access control (see openspec/changes/replace-ssh-cli-api/proposal.md, Slice 2a).
  *
  * Stores API principals (name + SSH public key + grants), answers authz
  * queries (deny-by-default), and renders the API account's `authorized_keys`

package/src/services/aspect-approvals.ts

@@ -1,7 +1,7 @@
 /**
  * Aspect approvals — operator consent for a module's base-module aspect.
  *
- * Per v2/CELILO_BASE.md D2: when an operator imports a module that
+ * Per openspec/specs/base-module-aspects/spec.md D2: when an operator imports a module that
  * declares a `base_module_aspect`, they consent to that aspect's
  * scope (applicable_zones + triggers) ONCE at import time. The
  * consent is recorded in the `aspect_approvals` table and consulted

package/src/services/aspect-runner.ts

@@ -2,7 +2,7 @@
  * Aspect runner — executes a module's base-module aspect across
  * the fleet.
  *
- * Per v2/CELILO_BASE.md Phase 1: when a module with an approved
+ * Per openspec/specs/base-module-aspects/spec.md Phase 1: when a module with an approved
  * `base_module_aspect` triggers a fan-out event, the runner walks
  * every non-`api_only` system in the aspect's `applicable_zones`,
  * materializes an Ansible inventory + playbook in a scratch
@@ -97,7 +97,7 @@ export interface AspectRunOptions {
   /**
    * Hostnames to exclude from fan-out, on top of `api_only`. The
    * primary deploy's own host(s) typically don't need the aspect
-   * (per v2/CELILO_BASE.md D3 — aspect authors handle this when
+   * (per openspec/specs/base-module-aspects/spec.md D3 — aspect authors handle this when
    * they want it, the framework doesn't force a skip).
    */
   excludeHostnames?: string[];
@@ -301,7 +301,7 @@ export async function materializeAspectAnsible(args: {
 /**
  * Execution-phase function: orchestrates plan + materialize + run.
  *
- * Failure semantics (v2/CELILO_BASE.md D4): aspects are idempotent
+ * Failure semantics (openspec/specs/base-module-aspects/spec.md D4): aspects are idempotent
  * and forward-progress only. A failed fan-out is reported and the
  * partial state (some systems updated, others not) is preserved —
  * no rollback. The caller (deploy planner, in SC4) decides how to

package/src/services/aspect-template-resolver.test.ts

@@ -14,7 +14,7 @@ const TEST_DB_PATH = './test-aspect-resolver.db';
  * resolver (separate from variables/resolver.ts); it previously handled
  * only $self:/$system:/$capability:, so knot's migrated
  * `knot_server_ip: $infra:main.ipv4_address` leaked into resolv.conf
- * unresolved and broke DNS on every fleet machine. v2/MODULE_SYSTEMS_ADDRESSING.md.
+ * unresolved and broke DNS on every fleet machine. openspec/specs/module-systems-addressing/spec.md.
  */
 function seedModuleWithSystem(db: DbClient, moduleId: string, ip: string): void {
   db.insert(modules)

package/src/services/aspect-template-resolver.ts

@@ -59,7 +59,7 @@ export async function resolveAspectTemplate(
   });
 
   // $infra:<system-name>.<field> — the provider's deployed system, by name
-  // (v2/MODULE_SYSTEMS_ADDRESSING.md). This is how an aspect references the
+  // (openspec/specs/module-systems-addressing/spec.md). This is how an aspect references the
   // provider's own host IP (e.g. knot's dns-client-config aspect sets every
   // fleet machine's nameserver to $infra:main.ipv4_address). Without this the
   // literal template string would leak into resolv.conf.

package/src/services/build-bus/delivery-events.ts

@@ -1,7 +1,7 @@
 /**
  * Local-bus event emitters for build-bus delivery outcomes.
  *
- * Phase 6 of [[v2/BUILD_BUS.md]] wants `celilo subscribers status`
+ * Phase 6 of [[openspec/changes/build-bus-poll-cd/proposal.md]] wants `celilo subscribers status`
  * to show last-delivery state + recent failures per subscriber. The
  * data source for that view is the local SQLite event bus — every
  * publisher-side fan-out call emits one `webhook.delivered` or

package/src/services/build-bus/fan-out.ts

@@ -1,5 +1,5 @@
 /**
- * Webhook fan-out for the build bus ([[v2/BUILD_BUS.md]] Phase 2).
+ * Webhook fan-out for the build bus ([[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 2).
  *
  * Given a PublishEvent and a subscriber list, this module:
  *   1. Filters subscribers whose match rule fires for the event.

package/src/services/build-bus/hook-dispatch.ts

@@ -1,6 +1,6 @@
 /**
  * Hook-dispatch planning + execution for the build bus
- * ([[v2/BUILD_BUS.md]] Phase 4).
+ * ([[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 4).
  *
  * Pure: planHookDispatch(event, modules) → HookDispatchPlan[].
  * Decides which module hooks match the event without spawning

package/src/services/build-bus/receiver-server.ts

@@ -1,6 +1,6 @@
 /**
  * HTTP receiver daemon for the build bus
- * ([[v2/BUILD_BUS.md]] Phase 3).
+ * ([[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 3).
  *
  * Verifies signed webhook envelopes against a per-receiver shared
  * secret, then re-emits the contained PublishEvent onto the local

package/src/services/build-bus/status.test.ts

@@ -1,5 +1,5 @@
 /**
- * Status-aggregator tests — Phase 6 of [[v2/BUILD_BUS.md]].
+ * Status-aggregator tests — Phase 6 of [[openspec/changes/build-bus-poll-cd/proposal.md]].
  *
  * The aggregator is pure: takes subscribers + delivery records,
  * returns per-subscriber summaries. The formatter is pure too.

package/src/services/build-bus/status.ts

@@ -1,6 +1,6 @@
 /**
  * Delivery-history aggregator for `celilo subscribers status`
- * ([[v2/BUILD_BUS.md]] Phase 6).
+ * ([[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 6).
  *
  * Reads recent `webhook.delivered` + `webhook.failed` events from
  * the local event bus, groups by subscriber URL, and produces a