@starci/skills 1.1.0

package/scripts/workspace-portable.mjs

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validatorFor } from './json-schema.mjs';
+
+const scriptRoot = dirname(fileURLToPath(import.meta.url));
+const starciRoot = resolve(scriptRoot, '..');
+const defaultSource = resolve(starciRoot, '..');
+const portableSchemaPath = join(starciRoot, 'readiness', 'initialization', 'workspaces', 'portable-route.schema.json');
+const localSchemaPath = join(starciRoot, 'readiness', 'initialization', 'workspaces', 'local-route.schema.json');
+const configSchemaPath = join(starciRoot, 'readiness', 'initialization', 'workspaces', 'config.schema.json');
+const validatePortableSchema = validatorFor(new URL('../readiness/initialization/workspaces/portable-route.schema.json', import.meta.url));
+const validateLocalSchema = validatorFor(new URL('../readiness/initialization/workspaces/local-route.schema.json', import.meta.url));
+const validateConfigSchema = validatorFor(new URL('../readiness/initialization/workspaces/config.schema.json', import.meta.url));
+const githubRemote = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:\.git)?$/;
+
+const slash = (value) => value.split(sep).join('/');
+const stableJson = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'));
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function value(args, flag) {
+  const index = args.indexOf(flag);
+  return index < 0 ? undefined : args[index + 1];
+}
+
+function samePath(left, right) {
+  const normalize = (path) => resolve(path).replaceAll('\\', '/').replace(/\/$/, '').toLowerCase();
+  return normalize(left) === normalize(right);
+}
+
+function inside(root, target) {
+  const result = relative(resolve(root), resolve(target));
+  return result !== '' && result !== '..' && !result.startsWith(`..${sep}`) && !isAbsolute(result);
+}
+
+function normalizeRemote(remote) {
+  return remote.trim().replace(/\.git$/i, '').replace(/\/$/, '').toLowerCase();
+}
+
+function git(repository, ...args) {
+  try {
+    return execFileSync('git', ['-C', repository, ...args], {
+      encoding: 'utf8',
+      windowsHide: true
+    }).trim();
+  } catch {
+    fail(`Git verification failed at ${repository}: git ${args.join(' ')}`);
+  }
+}
+
+function assertSchemaLink(documentPath, schemaRef) {
+  if (typeof schemaRef !== 'string' || schemaRef.length === 0) fail(`${documentPath} has no $schema`);
+  const target = resolve(dirname(documentPath), schemaRef);
+  if (!existsSync(target)) fail(`${documentPath} references missing schema ${target}`);
+  return target;
+}
+
+function assertPublicationSafe(document, label) {
+  const forbiddenKeys = new Set(['diskPath', 'gitRoot', 'head', 'updatedAt']);
+  const visit = (current, at) => {
+    if (typeof current === 'string') {
+      if (/credential|token|secret|password/i.test(current)) fail(`${at} contains secret-bearing text`);
+      if (/^[A-Za-z]:[\\/]/.test(current) || current.startsWith('/')) fail(`${at} contains an absolute path`);
+      if (/^https?:\/\/[^/\s]+@/i.test(current)) fail(`${at} contains URL user information`);
+      return;
+    }
+    if (Array.isArray(current)) {
+      current.forEach((item, index) => visit(item, `${at}[${index}]`));
+      return;
+    }
+    if (!current || typeof current !== 'object') return;
+    for (const [key, child] of Object.entries(current)) {
+      if (forbiddenKeys.has(key)) fail(`${at}.${key} contains observed machine state`);
+      if (/credential|token|secret|password/i.test(key)) fail(`${at}.${key} is secret-bearing`);
+      visit(child, `${at}.${key}`);
+    }
+  };
+  visit(document, label);
+}
+
+export function validatePortableRoute(route, label = 'portable route') {
+  const result = validatePortableSchema(route);
+  if (!result.valid) fail(`${label} is invalid:\n${result.errors.join('\n')}`);
+  if (!githubRemote.test(route.repository.gitRepository)) fail(`${label} has an invalid GitHub origin`);
+  if (route.schemaVersion === 6 && route.role !== 'fe' && route.context.grammarId !== null) {
+    fail(`${label} non-FE grammarId must be null`);
+  }
+  if (route.repository.gitPolicy?.mutationBranch !== undefined
+    && route.repository.gitPolicy.mutationBranch !== route.repository.branch) {
+    fail(`${label} gitPolicy.mutationBranch must equal repository.branch`);
+  }
+  assertPublicationSafe(route, label);
+  return route;
+}
+
+export function validateLocalRoute(route, label = 'local route') {
+  const result = validateLocalSchema(route);
+  if (!result.valid) fail(`${label} is invalid:\n${result.errors.join('\n')}`);
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(route.updatedAt)) {
+    fail(`${label}.updatedAt must be an ISO UTC timestamp`);
+  }
+  if (route.schemaVersion === 6 && route.role !== 'fe' && route.context.grammarId !== null) {
+    fail(`${label} non-FE grammarId must be null`);
+  }
+  if (route.repository.gitPolicy?.mutationBranch !== undefined
+    && route.repository.gitPolicy.mutationBranch !== route.repository.branch) {
+    fail(`${label} gitPolicy.mutationBranch must equal repository.branch`);
+  }
+  return route;
+}
+
+function directories(root) {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function jsonFiles(root) {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function loadDeclarations(source) {
+  const workspaceRoot = join(source, '.workspaces');
+  const configPath = join(workspaceRoot, 'config.json');
+  if (!existsSync(configPath)) fail(`workspace config is absent: ${configPath}`);
+  assertSchemaLink(configPath, readJson(configPath).$schema);
+  const configResult = validateConfigSchema(readJson(configPath));
+  if (!configResult.valid) fail(`workspace config is invalid:\n${configResult.errors.join('\n')}`);
+
+  const projectsRoot = join(workspaceRoot, 'projects');
+  const declarations = [];
+  for (const project of directories(projectsRoot)) {
+    for (const file of jsonFiles(join(projectsRoot, project))) {
+      const path = join(projectsRoot, project, file);
+      const route = readJson(path);
+      assertSchemaLink(path, route.$schema);
+      validatePortableRoute(route, slash(relative(source, path)));
+      if (route.project !== project || `${route.role}.json` !== file) fail(`${path} identity does not match its location`);
+      declarations.push({ path, route });
+    }
+  }
+  if (declarations.length === 0) fail(`portable workspace declarations are absent under ${projectsRoot}`);
+  return { workspaceRoot, declarations };
+}
+
+function resolveContextFile(repository, portablePath, label) {
+  const candidate = resolve(repository, portablePath);
+  if (!existsSync(candidate)) fail(`${label} is absent: ${candidate}`);
+  const actual = realpathSync(candidate);
+  if (!inside(repository, actual)) fail(`${label} escapes repository: ${portablePath}`);
+  return actual;
+}
+
+function buildLocalRoute({ source, repositoriesRoot, workspaceRoot, declaration }) {
+  const { route } = declaration;
+  const repositoryCandidate = route.repository.kind === 'source'
+    ? source
+    : resolve(repositoriesRoot, route.repository.directory);
+  if (!existsSync(repositoryCandidate) || !statSync(repositoryCandidate).isDirectory()) {
+    fail(`${route.project}/${route.role} checkout is absent: ${repositoryCandidate}`);
+  }
+  const repository = realpathSync(repositoryCandidate);
+  if (route.repository.kind === 'source') {
+    if (!samePath(repository, source)) fail(`${route.project}/${route.role} source route resolved outside Source`);
+  } else if (!inside(repositoriesRoot, repository)) {
+    fail(`${route.project}/${route.role} checkout escapes repositories root`);
+  }
+  const gitRoot = realpathSync(git(repository, 'rev-parse', '--show-toplevel'));
+  if (!samePath(gitRoot, repository)) fail(`${route.project}/${route.role} checkout is not its Git root`);
+  const observedRemote = git(repository, 'config', '--get', 'remote.origin.url');
+  if (normalizeRemote(observedRemote) !== normalizeRemote(route.repository.gitRepository)) {
+    fail(`${route.project}/${route.role} origin mismatch`);
+  }
+  const branch = git(repository, 'branch', '--show-current');
+  if (branch !== route.repository.branch) fail(`${route.project}/${route.role} branch mismatch: expected ${route.repository.branch}, observed ${branch}`);
+
+  const context = route.context;
+  const absoluteList = (paths, label) => paths.map((path, index) => resolveContextFile(repository, path, `${route.project}/${route.role} ${label}[${index}]`));
+  const commonContext = {
+    instructions: absoluteList(context.instructions, 'instruction'),
+    manifests: absoluteList(context.manifests, 'manifest')
+  };
+  const v6 = route.schemaVersion === 6;
+  const local = {
+    $schema: '../../../../../.claude/readiness/initialization/workspaces/local-route.schema.json',
+    ...(v6 ? { schemaVersion: 6, schemaRevision: 2 } : { version: 1 }),
+    project: route.project,
+    role: route.role,
+    source: {
+      path: source,
+      trust: join(source, '.claude'),
+      skills: join(source, '.claude', 'skills'),
+      workspaceRoot
+    },
+    repository: {
+      diskPath: repository,
+      gitRoot: repository,
+      gitRepository: route.repository.gitRepository,
+      branch,
+      head: git(repository, 'rev-parse', 'HEAD'),
+      ...(route.repository.gitPolicy ? { gitPolicy: route.repository.gitPolicy } : {})
+    },
+    context: v6
+      ? {
+          ...commonContext,
+          contract: (context.contract ?? null) === null
+            ? null
+            : resolveContextFile(repository, context.contract, `${route.project}/${route.role} contract`),
+          contractSource: context.contractSource ?? null,
+          grammarId: context.grammarId
+        }
+      : { ...commonContext, grammar: context.grammar, grammarProfile: context.grammarProfile },
+    updatedAt: new Date().toISOString()
+  };
+  validateLocalRoute(local, `${route.project}/${route.role} hydrated route`);
+  return {
+    target: join(workspaceRoot, 'local', 'routes', route.project, route.role, 'config.json'),
+    value: local
+  };
+}
+
+function comparable(route) {
+  const value = structuredClone(route);
+  delete value.updatedAt;
+  return value;
+}
+
+function changed(target, expected) {
+  if (!existsSync(target)) return true;
+  try {
+    const actual = readJson(target);
+    return JSON.stringify(comparable(actual)) !== JSON.stringify(comparable(expected));
+  } catch {
+    return true;
+  }
+}
+
+function atomicWrite(target, value) {
+  mkdirSync(dirname(target), { recursive: true });
+  const temporary = join(dirname(target), `.${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`);
+  try {
+    writeFileSync(temporary, stableJson(value), { encoding: 'utf8', flag: 'wx' });
+    renameSync(temporary, target);
+  } finally {
+    if (existsSync(temporary)) rmSync(temporary, { force: true });
+  }
+}
+
+function checkoutPlans(repositoriesRoot, declarations) {
+  const byDirectory = new Map();
+  for (const { route } of declarations) {
+    if (route.repository.kind === 'source') continue;
+    const key = route.repository.directory;
+    const previous = byDirectory.get(key);
+    if (previous && (
+      normalizeRemote(previous.gitRepository) !== normalizeRemote(route.repository.gitRepository)
+      || previous.branch !== route.repository.branch
+    )) fail(`conflicting checkout declarations for ${key}`);
+    byDirectory.set(key, route.repository);
+  }
+  return [...byDirectory.values()].sort((left, right) => left.directory.localeCompare(right.directory)).map((repository) => {
+    const target = resolve(repositoriesRoot, repository.directory);
+    if (!inside(repositoriesRoot, target)) fail(`checkout target escapes repositories root: ${repository.directory}`);
+    return { ...repository, target };
+  });
+}
+
+function checkoutGitEnvironment(source, credentialFile) {
+  const env = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
+  if (!credentialFile) return env;
+  const path = resolve(source, credentialFile);
+  if (!inside(source, path) || !existsSync(path)) fail(`checkout credential file is absent or outside Source: ${credentialFile}`);
+  const token = readFileSync(path, 'utf8').trim();
+  if (token === '') fail(`checkout credential file is empty: ${credentialFile}`);
+  const parsedCount = Number.parseInt(env.GIT_CONFIG_COUNT ?? '0', 10);
+  const index = Number.isSafeInteger(parsedCount) && parsedCount >= 0 ? parsedCount : 0;
+  env.GIT_CONFIG_COUNT = String(index + 1);
+  env[`GIT_CONFIG_KEY_${index}`] = 'http.https://github.com/.extraheader';
+  env[`GIT_CONFIG_VALUE_${index}`] = `Authorization: Basic ${Buffer.from(`x-access-token:${token}`, 'utf8').toString('base64')}`;
+  return env;
+}
+
+function initializeCheckouts(plans, env) {
+  const initialized = [];
+  for (const plan of plans) {
+    if (existsSync(plan.target)) continue;
+    try {
+      execFileSync('git', [
+        'clone',
+        '--quiet',
+        '--single-branch',
+        '--branch',
+        plan.branch,
+        '--',
+        plan.gitRepository,
+        plan.target
+      ], { encoding: 'utf8', env, windowsHide: true });
+      execFileSync('git', ['-C', plan.target, 'remote', 'set-url', 'origin', plan.gitRepository], {
+        encoding: 'utf8',
+        env,
+        windowsHide: true
+      });
+    } catch {
+      fail(`checkout initialization failed: ${plan.gitRepository} -> ${plan.target}`);
+    }
+    initialized.push(plan.target);
+  }
+  return initialized;
+}
+
+export function run(argv = process.argv.slice(2)) {
+  const command = argv[0];
+  if (!['bootstrap', 'hydrate', 'check'].includes(command)) fail('Usage: workspace-portable.mjs <bootstrap|hydrate|check> --source <Source> [--repositories-root <path>] [--project <id>] [--credential-file <Source-relative path>] [--plan|--apply]');
+  const plan = argv.includes('--plan');
+  const apply = argv.includes('--apply');
+  if (['bootstrap', 'hydrate'].includes(command) && plan === apply) fail(`${command} requires exactly one of --plan or --apply`);
+  if (command === 'check' && (plan || apply)) fail('check accepts neither --plan nor --apply');
+
+  if (!existsSync(portableSchemaPath) || !existsSync(localSchemaPath) || !existsSync(configSchemaPath)) fail('V6 workspace schemas are incomplete');
+  const source = realpathSync(resolve(value(argv, '--source') ?? defaultSource));
+  const repositoriesRoot = realpathSync(resolve(value(argv, '--repositories-root') ?? dirname(source)));
+  const project = value(argv, '--project');
+  const credentialFile = value(argv, '--credential-file');
+  if (credentialFile && command !== 'bootstrap') fail('--credential-file is accepted only by bootstrap');
+  const { workspaceRoot, declarations } = loadDeclarations(source);
+  const selected = project ? declarations.filter((item) => item.route.project === project) : declarations;
+  if (selected.length === 0) fail(`no workspace declarations selected${project ? ` for ${project}` : ''}`);
+
+  const checkoutPlan = command === 'bootstrap' ? checkoutPlans(repositoriesRoot, selected) : [];
+  const missingCheckouts = checkoutPlan.filter((item) => !existsSync(item.target));
+  if (command === 'bootstrap' && plan && missingCheckouts.length > 0) {
+    console.log(JSON.stringify({
+      status: 'initialize-required',
+      routeCount: selected.length,
+      missingCheckouts: missingCheckouts.map((item) => slash(relative(repositoriesRoot, item.target))),
+      changedRoutes: []
+    }));
+    return 0;
+  }
+  const initializedCheckouts = command === 'bootstrap' && apply
+    ? initializeCheckouts(checkoutPlan, checkoutGitEnvironment(source, credentialFile))
+    : [];
+
+  const expected = selected.map((declaration) => buildLocalRoute({ source, repositoriesRoot, workspaceRoot, declaration }));
+  const changes = expected.filter((item) => changed(item.target, item.value));
+  if ((command === 'hydrate' || command === 'bootstrap') && apply) changes.forEach((item) => atomicWrite(item.target, item.value));
+  const summary = {
+    status: command === 'check' && changes.length > 0 ? 'stale' : 'ready',
+    routeCount: expected.length,
+    ...(command === 'bootstrap' ? {
+      initializedCheckouts: initializedCheckouts.map((item) => slash(relative(repositoriesRoot, item)))
+    } : {}),
+    changedRoutes: changes.map((item) => slash(relative(source, item.target)))
+  };
+  console.log(JSON.stringify(summary));
+  return command === 'check' && changes.length > 0 ? 1 : 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    process.exitCode = run();
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/scripts/workspace-portable.spec.mjs

@@ -0,0 +1,246 @@
+import assert from 'node:assert/strict';
+import { execFileSync, spawnSync } from 'node:child_process';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import test from 'node:test';
+import { validatePortableRoute } from './workspace-portable.mjs';
+
+const script = fileURLToPath(new URL('./workspace-portable.mjs', import.meta.url));
+const schemaRoot = fileURLToPath(new URL('../readiness/initialization/workspaces/', import.meta.url));
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function git(repository, ...args) {
+  return execFileSync('git', ['-C', repository, ...args], { encoding: 'utf8', windowsHide: true }).trim();
+}
+
+function repository(path, remote) {
+  mkdirSync(path, { recursive: true });
+  execFileSync('git', ['init', '-b', 'main', path], { stdio: 'ignore', windowsHide: true });
+  git(path, 'config', 'user.name', 'Test');
+  git(path, 'config', 'user.email', 'test@example.com');
+  git(path, 'remote', 'add', 'origin', remote);
+  writeFileSync(join(path, 'package.json'), '{}\n');
+  git(path, 'add', 'package.json');
+  git(path, 'commit', '-m', 'fixture');
+}
+
+function fixture(t) {
+  const repositories = mkdtempSync(join(tmpdir(), 'starci-v6-workspaces-'));
+  const source = join(repositories, 'source');
+  const frontend = join(repositories, 'nivo-fe');
+  t.after(() => rmSync(repositories, { recursive: true, force: true }));
+  repository(source, 'https://github.com/starci-lab/source.git');
+  repository(frontend, 'https://github.com/starci-lab/nivo-fe.git');
+  const frontendContract = join(frontend, 'packages', 'ui', 'src', 'contracts', 'index.ts');
+  mkdirSync(dirname(frontendContract), { recursive: true });
+  writeFileSync(frontendContract, 'export const CONTRACTS = {};\n');
+  git(frontend, 'add', 'packages/ui/src/contracts/index.ts');
+  git(frontend, 'commit', '-m', 'contract fixture');
+  mkdirSync(join(source, '.claude', 'readiness', 'initialization', 'workspaces'), { recursive: true });
+  for (const name of ['config.schema.json', 'portable-route.schema.json', 'local-route.schema.json']) {
+    copyFileSync(join(schemaRoot, name), join(source, '.claude', 'readiness', 'initialization', 'workspaces', name));
+  }
+  mkdirSync(join(source, '.claude', 'skills'), { recursive: true });
+  writeJson(join(source, '.workspaces', 'config.json'), {
+    $schema: '../.claude/readiness/initialization/workspaces/config.schema.json',
+    schemaVersion: 6,
+    defaultLang: 'vi'
+  });
+  writeJson(join(source, '.workspaces', 'projects', 'source', 'be.json'), {
+    $schema: '../../../.claude/readiness/initialization/workspaces/portable-route.schema.json',
+    version: 1,
+    project: 'source',
+    role: 'be',
+    repository: { kind: 'source', directory: null, gitRepository: 'https://github.com/starci-lab/source.git', branch: 'main' },
+    context: { instructions: [], manifests: ['package.json'], grammar: null, grammarProfile: null }
+  });
+  writeJson(join(source, '.workspaces', 'projects', 'nivo', 'fe.json'), {
+    $schema: '../../../.claude/readiness/initialization/workspaces/portable-route.schema.json',
+    schemaVersion: 6,
+    schemaRevision: 2,
+    project: 'nivo',
+    role: 'fe',
+    repository: {
+      kind: 'sibling', directory: 'nivo-fe', gitRepository: 'https://github.com/starci-lab/nivo-fe.git', branch: 'main',
+      gitPolicy: { mutationBranch: 'main', worktreeBranches: 'forbidden', incomingBranchRefs: 'merge-into-mutation-branch' }
+    },
+    context: {
+      instructions: [],
+      contract: 'packages/ui/src/contracts/index.ts',
+      contractSource: 'discovered:packages/ui/src/contracts/index.ts',
+      manifests: ['package.json'],
+      grammarId: 'core'
+    }
+  });
+  mkdirSync(join(source, '.workspaces', 'local', 'credentials'), { recursive: true });
+  writeFileSync(join(source, '.workspaces', 'local', 'credentials', 'provider.key.enc'), 'ciphertext');
+  return { repositories, source, frontend };
+}
+
+function runScript(fixture, ...args) {
+  return spawnSync(process.execPath, [script, ...args, '--source', fixture.source, '--repositories-root', fixture.repositories], {
+    encoding: 'utf8',
+    windowsHide: true
+  });
+}
+
+function runScriptWithEnv(fixture, env, ...args) {
+  return spawnSync(process.execPath, [script, ...args, '--source', fixture.source, '--repositories-root', fixture.repositories], {
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+    windowsHide: true
+  });
+}
+
+test('hydrates V1 and V6 routes, refreshes stale heads, and preserves credentials', (t) => {
+  const f = fixture(t);
+  let result = runScript(f, 'hydrate', '--apply');
+  assert.equal(result.status, 0, result.stderr);
+  const v1Path = join(f.source, '.workspaces', 'local', 'routes', 'source', 'be', 'config.json');
+  const v6Path = join(f.source, '.workspaces', 'local', 'routes', 'nivo', 'fe', 'config.json');
+  assert.equal(JSON.parse(readFileSync(v1Path, 'utf8')).version, 1);
+  const v6 = JSON.parse(readFileSync(v6Path, 'utf8'));
+  assert.equal(v6.schemaVersion, 6);
+  assert.equal(v6.schemaRevision, 2);
+  assert.equal(v6.context.contract, realpathSync(join(f.frontend, 'packages', 'ui', 'src', 'contracts', 'index.ts')));
+  assert.equal(v6.context.contractSource, 'discovered:packages/ui/src/contracts/index.ts');
+  assert.equal(v6.context.grammarId, 'core');
+  assert.deepEqual(v6.repository.gitPolicy, {
+    mutationBranch: 'main',
+    worktreeBranches: 'forbidden',
+    incomingBranchRefs: 'merge-into-mutation-branch'
+  });
+  assert.equal(v6.repository.head, git(f.frontend, 'rev-parse', 'HEAD'));
+  assert.equal(readFileSync(join(f.source, '.workspaces', 'local', 'credentials', 'provider.key.enc'), 'utf8'), 'ciphertext');
+
+  const unchanged = readFileSync(v6Path, 'utf8');
+  result = runScript(f, 'hydrate', '--apply');
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(readFileSync(v6Path, 'utf8'), unchanged);
+
+  writeFileSync(join(f.frontend, 'next.config.ts'), 'export default {};\n');
+  git(f.frontend, 'add', 'next.config.ts');
+  git(f.frontend, 'commit', '-m', 'advance');
+  result = runScript(f, 'check');
+  assert.equal(result.status, 1, result.stderr);
+  result = runScript(f, 'hydrate', '--apply');
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(JSON.parse(readFileSync(v6Path, 'utf8')).repository.head, git(f.frontend, 'rev-parse', 'HEAD'));
+  assert.equal(runScript(f, 'check').status, 0);
+});
+
+test('bootstrap clones a missing declared sibling and hydrates it without user-specific Git config', (t) => {
+  const f = fixture(t);
+  const bare = join(f.repositories, 'nivo-fe-origin.git');
+  execFileSync('git', ['clone', '--quiet', '--bare', f.frontend, bare], { windowsHide: true });
+  rmSync(f.frontend, { recursive: true, force: true });
+  const remote = 'https://github.com/starci-lab/nivo-fe.git';
+  const env = {
+    GIT_CONFIG_COUNT: '1',
+    GIT_CONFIG_KEY_0: `url.${pathToFileURL(bare).href}.insteadOf`,
+    GIT_CONFIG_VALUE_0: remote
+  };
+
+  const plan = runScriptWithEnv(f, env, 'bootstrap', '--plan', '--project', 'nivo');
+  assert.equal(plan.status, 0, plan.stderr);
+  assert.deepEqual(JSON.parse(plan.stdout).missingCheckouts, ['nivo-fe']);
+
+  const applied = runScriptWithEnv(f, env, 'bootstrap', '--apply', '--project', 'nivo');
+  assert.equal(applied.status, 0, applied.stderr);
+  assert.deepEqual(JSON.parse(applied.stdout).initializedCheckouts, ['nivo-fe']);
+  assert.equal(git(f.frontend, 'remote', 'get-url', 'origin'), remote);
+  assert.equal(runScript(f, 'check', '--project', 'nivo').status, 0);
+});
+
+test('current V6 rejects legacy grammar fields, mixed versions, and non-FE grammar while accepting the immediate predecessor', () => {
+  const base = {
+    $schema: '../../../.claude/readiness/initialization/workspaces/portable-route.schema.json',
+    schemaVersion: 6,
+    schemaRevision: 2,
+    project: 'nivo',
+    role: 'fe',
+    repository: {
+      kind: 'sibling', directory: 'nivo-fe', gitRepository: 'https://github.com/starci-lab/nivo-fe.git', branch: 'main',
+      gitPolicy: { mutationBranch: 'main', worktreeBranches: 'forbidden', incomingBranchRefs: 'merge-into-mutation-branch' }
+    },
+    context: {
+      instructions: [],
+      contract: null,
+      contractSource: null,
+      manifests: ['package.json'],
+      grammarId: 'core'
+    }
+  };
+  const preContractV6 = structuredClone(base);
+  delete preContractV6.schemaRevision;
+  delete preContractV6.context.contract;
+  delete preContractV6.context.contractSource;
+  assert.doesNotThrow(() => validatePortableRoute(preContractV6));
+  const pairedUnrevisionedV6 = structuredClone(base);
+  delete pairedUnrevisionedV6.schemaRevision;
+  assert.doesNotThrow(() => validatePortableRoute(pairedUnrevisionedV6));
+  assert.throws(() => validatePortableRoute({ ...base, version: 1 }), /invalid/);
+  assert.throws(() => validatePortableRoute({ ...base, context: { ...base.context, grammar: 'starci' } }), /invalid/);
+  assert.throws(() => validatePortableRoute({ ...base, role: 'be' }), /non-FE grammarId must be null|invalid/);
+  assert.throws(() => validatePortableRoute({
+    ...base,
+    context: { ...base.context, contract: 'packages/ui/src/contracts/index.ts', contractSource: null }
+  }), /invalid/);
+  assert.throws(() => validatePortableRoute({
+    ...base,
+    context: { ...base.context, contract: null, contractSource: 'discovered:packages/ui/src/contracts/index.ts' }
+  }), /invalid/);
+  assert.throws(() => validatePortableRoute({ ...base, repository: { ...base.repository, directory: '../nivo-fe' } }), /invalid/);
+  assert.throws(() => validatePortableRoute({ ...base, repository: { ...base.repository, gitRepository: 'https://token@github.com/starci-lab/nivo-fe.git' } }), /invalid/);
+  assert.throws(() => validatePortableRoute({
+    ...base,
+    repository: { ...base.repository, gitPolicy: { ...base.repository.gitPolicy, mutationBranch: 'feature/task' } }
+  }), /mutationBranch must equal repository\.branch/);
+});
+
+test('a session-only worktree policy hydrates and is kept verbatim', (t) => {
+  const f = fixture(t);
+  const declPath = join(f.source, '.workspaces', 'projects', 'nivo', 'fe.json');
+  const decl = JSON.parse(readFileSync(declPath, 'utf8'));
+  decl.repository.gitPolicy.worktreeBranches = 'session-only';
+  writeFileSync(declPath, JSON.stringify(decl, null, 2));
+  const result = runScript(f, 'hydrate', '--apply');
+  assert.equal(result.status, 0, result.stderr);
+  const v6 = JSON.parse(readFileSync(join(f.source, '.workspaces', 'local', 'routes', 'nivo', 'fe', 'config.json'), 'utf8'));
+  assert.equal(v6.repository.gitPolicy.worktreeBranches, 'session-only');
+});
+
+test('direct-main policy blocks hydration from a feature branch', (t) => {
+  const f = fixture(t);
+  git(f.frontend, 'switch', '-c', 'feature/task');
+  const result = runScript(f, 'hydrate', '--apply');
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /branch mismatch: expected main, observed feature\/task/);
+});
+
+test('a failing declaration produces no partial local route writes', (t) => {
+  const f = fixture(t);
+  const declaration = join(f.source, '.workspaces', 'projects', 'nivo', 'fe.json');
+  const value = JSON.parse(readFileSync(declaration, 'utf8'));
+  value.repository.branch = 'missing-branch';
+  writeJson(declaration, value);
+  const result = runScript(f, 'hydrate', '--apply');
+  assert.equal(result.status, 1);
+  assert.equal(existsSync(join(f.source, '.workspaces', 'local', 'routes', 'source', 'be', 'config.json')), false);
+  assert.equal(existsSync(join(f.source, '.workspaces', 'local', 'routes', 'nivo', 'fe', 'config.json')), false);
+});