@llman-sdd/core 0.1.4 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/core",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Pure domain logic for llman-sdd (config, gherkin specs, validation, templates)",
   "license": "MIT",
   "repository": {

package/src/archive/freeze.ts

@@ -88,7 +88,7 @@ export async function runFreeze(
 export async function runList(io: FreezeIo, sz: SevenZipPort, rootAbs: string): Promise<string[]> {
   const archiveAbs = join(rootAbs, ARCHIVE_DIR_REL, FREEZE_ARCHIVE_NAME);
   if (!io.exists(archiveAbs)) {
-    return [`No freeze archive found at ./${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME}`];
+    return [`freeze archive not found: ./${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME}`];
   }
   // Real 7z lists file paths under their directory (`<dir>/proposal.md`);
   // directory entries themselves are skipped by parseListNames. Derive the
@@ -117,10 +117,13 @@ export async function runThaw(
   sz: SevenZipPort,
   rootAbs: string,
   names: string[],
+  opts: { dest?: string } = {},
 ): Promise<ThawResult> {
+  // r56: restore target override (created on demand); default = changes/archive
+  const destRel = opts.dest ?? ARCHIVE_DIR_REL;
   const archiveAbs = join(rootAbs, ARCHIVE_DIR_REL, FREEZE_ARCHIVE_NAME);
   if (!io.exists(`${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME}`)) {
-    throw new Error(`No freeze archive found at ./${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME}`);
+    throw new Error(`freeze archive not found: ./${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME}`);
   }
   const tmpRel = 'llmanspec/.thaw-tmp';
   const tmpAbs = join(rootAbs, tmpRel);
@@ -136,15 +139,15 @@ export async function runThaw(
     }
     const restored: string[] = [];
     for (const name of names.toSorted()) {
-      if (io.exists(`${ARCHIVE_DIR_REL}/${name}`)) {
+      if (io.exists(`${destRel}/${name}`)) {
         throw new Error(`target already exists: ${name}`);
       }
-      io.moveDir(`${tmpRel}/${name}`, `${ARCHIVE_DIR_REL}/${name}`);
+      io.moveDir(`${tmpRel}/${name}`, `${destRel}/${name}`);
       restored.push(name);
     }
     return {
       restored,
-      lines: [`Thawed ${restored.length} selected archived changes to ${ARCHIVE_DIR_REL}`],
+      lines: [`Thawed ${restored.length} selected archived changes to ${destRel}`],
     };
   } finally {
     io.removeDir(tmpRel);

package/src/change/id.ts

@@ -1,43 +1,63 @@
 /**
- * Change id derivation (change-lifecycle capability): legal ids are
- * verb-prefixed kebab-case ASCII, ≤60 chars (CLI-checked convention).
+ * Change id derivation (change-lifecycle capability): v1 `change/new.rs`
+ * `derive_change_id` parity — pure kebab sanitization (lowercase alnum,
+ * separators), no verb requirement, empty/oversized handling.
  */
-const VERBS = [
-  'bootstrap',
-  'port',
-  'add',
-  'update',
-  'remove',
-  'refactor',
-  'fix',
-  'release',
-  'migrate',
-  'init',
-  'draft',
-  'archive',
-] as const;
 
 const ID_CAP = 60;
 
+export class ChangeIdError extends Error {}
+
 export function isLegalChangeId(id: string): boolean {
-  return (
-    VERBS.some((v) => id === v || id.startsWith(`${v}-`)) &&
-    /^[a-z0-9-]+$/u.test(id) &&
-    id.length <= ID_CAP
-  );
+  return /^[a-z0-9-]+$/u.test(id) && id.length > 0 && id.length <= ID_CAP;
 }
 
+/** v1 parity: sanitize to lowercase kebab (ASCII alnum only; CJK/punct dropped). */
 export function deriveChangeId(description: string): string {
-  let id = description
-    .toLowerCase()
-    .normalize('NFKD')
-    .replaceAll(/[^a-z0-9]+/gu, '-')
-    .replaceAll(/^-+|-+$/gu, '')
-    .slice(0, ID_CAP)
-    .replaceAll(/-+$/gu, '');
-  if (id === '') id = 'change';
-  if (isLegalChangeId(id)) return id;
-  return `add-${id}`.slice(0, ID_CAP).replaceAll(/-+$/gu, '');
+  const trimmed = description.trim();
+  if (trimmed === '') {
+    throw new ChangeIdError('--from <DESCRIPTION> must be non-empty');
+  }
+  let id = '';
+  let prevDash = true;
+  for (const ch of trimmed) {
+    if (/[a-zA-Z0-9]/u.test(ch)) {
+      id += ch.toLowerCase();
+      prevDash = false;
+    } else if (
+      /\s/u.test(ch) ||
+      ch === '_' ||
+      ch === '.' ||
+      ch === '-' ||
+      ch === '/' ||
+      ch === '\\'
+    ) {
+      if (!prevDash) {
+        id += '-';
+        prevDash = true;
+      }
+    } else {
+      // Punctuation / CJK etc.: drop (CJK intentionally dropped to keep ids
+      // ASCII-friendly); a dropped char at a word boundary yields a `-`.
+      if (!prevDash) {
+        id += '-';
+        prevDash = true;
+      }
+    }
+  }
+  while (id.endsWith('-')) id = id.slice(0, -1);
+  if (id === '') {
+    throw new ChangeIdError(
+      '--from <DESCRIPTION> yielded an empty id after sanitizing; provide a description with at least one alphanumeric character',
+    );
+  }
+  if (id.length > ID_CAP) {
+    const cutoff = id.slice(0, ID_CAP).lastIndexOf('-');
+    const at = cutoff === -1 ? ID_CAP : cutoff;
+    id = id.slice(0, at);
+    while (id.endsWith('-')) id = id.slice(0, -1);
+  }
+  return id;
 }
 
 export const DRAFT_PROPOSAL_TEMPLATE = `## Why

package/src/change/lifecycle.ts

@@ -1,7 +1,9 @@
 import {
   currentBranch,
   defaultBranch,
+  dirtyCount,
   isCleanTree,
+  mergeBase,
   revParseHead,
   type GitLike,
 } from '../git/spawnGit.ts';
@@ -33,14 +35,18 @@ export function changeExists(io: FsIo, id: string): boolean {
   return io.exists(proposalPath(id));
 }
 
-/** `change new [id] --from DESC`: derive a legal id and write the draft shell. */
+/** `change new [id] --from DESC --force`: derive a legal id and write the draft shell. */
 export function newChange(
   io: FsIo,
-  opts: { id?: string; from?: string },
+  opts: { id?: string; from?: string; force?: boolean },
 ): { id: string; path: string } {
   const id = opts.id ?? deriveChangeId(opts.from ?? '');
   const path = proposalPath(id);
-  if (io.exists(path)) throw new LifecycleError(`change \`${id}\` already exists: ${path}`);
+  if (io.exists(path) && !opts.force) {
+    throw new LifecycleError(
+      `change proposal already exists: ./${path} (pass --force to overwrite)`,
+    );
+  }
   io.writeText(path, `---\ndepends_on: []\n---\n\n${DRAFT_PROPOSAL_TEMPLATE}`);
   return { id, path };
 }
@@ -54,35 +60,73 @@ export function startChange(
 ): { branch: string; baseBranch: string; baseSha: string } {
   const path = proposalPath(id);
   if (!io.exists(path)) throw new LifecycleError(`proposal not found: ${path}`);
-  if (!isCleanTree(git))
-    throw new LifecycleError('working tree is not clean — commit or stash first');
+  const dirty = dirtyCount(git);
+  if (dirty > 0)
+    throw new LifecycleError(
+      `dirty tree: ${dirty} uncommitted files; commit/stash before \`change start\``,
+    );
   const baseBranch = defaultBranch(git);
   const here = currentBranch(git);
-  if (here !== baseBranch) {
+  if (here !== null && here !== baseBranch) {
     throw new LifecycleError(
-      `must run from the default branch (${baseBranch}), currently on: ${here ?? 'detached'}`,
+      `already on non-default branch \`${here}\`; use \`change attach\` to bind it, or switch to the default branch before \`change start\``,
     );
   }
+  if (here === null) throw new LifecycleError('detached HEAD is not allowed for change binding');
   const branchPrefix = opts.branchPrefix ?? 'sdd/';
   const branch = `${branchPrefix}${id}`;
   git.run(['switch', '-c', branch]);
-  const baseSha = revParseHead(git);
+  const baseSha =
+    currentBranch(git) !== null ? mergeBase(git, 'HEAD', baseBranch) : revParseHead(git);
   io.writeText(path, writeBinding(io.readText(path), { branch, baseBranch, baseSha }));
   return { branch, baseBranch, baseSha };
 }
 
-/** `change attach`: bind the current branch without gates. */
-export function attachChange(git: GitLike, io: FsIo, id: string): { branch: string } {
+/** `change attach`: bind the current branch — same branch gate family as start (r31). */
+export function attachChange(
+  git: GitLike,
+  io: FsIo,
+  id: string,
+  opts: { force?: boolean; base?: string } = {},
+): { branch: string; baseBranch: string; baseSha: string } {
   const path = proposalPath(id);
   if (!io.exists(path)) throw new LifecycleError(`proposal not found: ${path}`);
+  const existing = readBinding(io.readText(path));
+  if (!opts.force && existing !== null) {
+    throw new LifecycleError(
+      `change \`${id}\` already attached to branch \`${existing.branch}\` (base ${existing.baseSha}); pass --force to rebind`,
+    );
+  }
+  const configuredBase = opts.base ?? defaultBranch(git);
   const branch = currentBranch(git);
-  if (branch === null) throw new LifecycleError('detached HEAD — cannot attach');
-  const baseSha = revParseHead(git);
+  if (branch === null || branch === '') {
+    throw new LifecycleError('detached HEAD is not allowed for change binding');
+  }
+  if (opts.base !== undefined) {
+    if (
+      git.runOpt(['show-ref', '--verify', '--quiet', `refs/heads/${opts.base}`]) === null &&
+      git.runOpt(['show-ref', '--verify', '--quiet', `refs/remotes/${opts.base}`]) === null
+    ) {
+      throw new LifecycleError(
+        `base branch \`${opts.base}\` does not exist; --base records the fork source branch for merge-target resolution (r111)`,
+      );
+    }
+    if (opts.base === branch) {
+      throw new LifecycleError(`--base must differ from the bound branch \`${branch}\``);
+    }
+  }
+  if (branch === configuredBase) {
+    throw new LifecycleError(
+      `changes must not attach on the default branch (\`${branch}\`); ` +
+        'create/switch to a feature branch first (or use `change start`)',
+    );
+  }
+  const baseSha = mergeBase(git, branch, configuredBase);
   io.writeText(
     path,
-    writeBinding(io.readText(path), { branch, baseBranch: defaultBranch(git), baseSha }),
+    writeBinding(io.readText(path), { branch, baseBranch: configuredBase, baseSha }),
   );
-  return { branch };
+  return { branch, baseBranch: configuredBase, baseSha };
 }
 
 export interface FinalizeResult {
@@ -92,46 +136,149 @@ export interface FinalizeResult {
   commitSubject: string;
 }
 
+export interface ArchiveTaskGate {
+  blocked: boolean;
+  reasons: string[];
+}
+
+/** r40 task gate: unchecked tasks always block; ratio gate when configured. */
+export function archiveTaskGate(
+  tasksMd: string | null,
+  minCompletionRatio: number | undefined,
+): ArchiveTaskGate {
+  const reasons: string[] = [];
+  if (tasksMd !== null) {
+    let completed = 0;
+    let total = 0;
+    for (const line of tasksMd.split('\n')) {
+      const m = line.match(/^\s*-\s+\[( |x|X)\]/u);
+      if (m) {
+        total += 1;
+        if (m[1] !== ' ') completed += 1;
+      }
+    }
+    if (total > 0 && completed < total) {
+      reasons.push(`archive blocked by unchecked tasks (${total - completed}/${total} pending)`);
+      for (const line of tasksMd.split('\n')) {
+        if (/^\s*-\s+\[ \]/u.test(line)) reasons.push(line.trim());
+      }
+    }
+    if (minCompletionRatio !== undefined && total > 0 && completed / total < minCompletionRatio) {
+      reasons.push(
+        `completion ${((completed / total) * 100).toFixed(0)}% below archive.min_completion_ratio ${(minCompletionRatio * 100).toFixed(0)}%`,
+      );
+    }
+  }
+  return { blocked: reasons.length > 0, reasons };
+}
+
 /** `change finalize`: merge (squash default) + archive rename + close-out commit. */
 export function finalizeChange(
   git: GitLike,
   io: FsIo,
   id: string,
-  opts: { into?: string; method?: 'squash' | 'ff'; today?: string } = {},
+  opts: { into?: string; method?: 'squash' | 'ff'; today?: string; noCommit?: boolean } = {},
 ): FinalizeResult {
   const path = proposalPath(id);
   const binding = readBinding(io.readText(path));
   if (binding === null) {
     throw new LifecycleError(`change \`${id}\` has no branch binding — run start/attach first`);
   }
+  // r15 (v1 r94): finalize runs on the bound branch — any other branch must
+  // fail before any write (no switch, no merge, no rename).
+  const current = currentBranch(git);
+  if (current !== binding.branch) {
+    throw new LifecycleError(
+      `finalize must run on the bound branch \`${binding.branch}\` (current: ${current ?? 'detached HEAD'})`,
+    );
+  }
   const method = opts.method ?? 'squash';
   const target = opts.into ?? binding.baseBranch ?? defaultBranch(git);
-  const warnings: string[] = [];
+  return mergeRenameCommit(git, io, id, binding.branch, target, method, opts.today, opts.noCommit);
+}
 
-  // Read the binding while still on the feature branch (its proposal.md may
-  // carry uncommitted binding edits), then switch and merge.
+/** Shared close-out: merge → archive rename → single archive(sdd) commit. */
+function mergeRenameCommit(
+  git: GitLike,
+  io: FsIo,
+  id: string,
+  featureBranch: string,
+  target: string,
+  method: 'squash' | 'ff',
+  today?: string,
+  noCommit?: boolean,
+): FinalizeResult {
+  const warnings: string[] = [];
   git.run(['switch', target]);
   const mergeArgs =
-    method === 'ff'
-      ? ['merge', '--ff-only', binding.branch]
-      : ['merge', '--squash', binding.branch];
+    method === 'ff' ? ['merge', '--ff-only', featureBranch] : ['merge', '--squash', featureBranch];
   if (git.runOpt(mergeArgs) === null) {
     git.runOpt(['merge', '--abort']);
     warnings.push(
-      `merge ${method} failed — resolve manually, e.g. \`git merge ${method === 'ff' ? '--ff-only' : '--squash'} ${binding.branch}\``,
+      `merge ${method} failed — resolve manually, e.g. \`git merge ${method === 'ff' ? '--ff-only' : '--squash'} ${featureBranch}\``,
     );
   }
 
-  const date = opts.today ?? new Date().toISOString().slice(0, 10);
+  const date = today ?? new Date().toISOString().slice(0, 10);
   const archiveDir = `${CHANGES_DIR}/archive/${date}-${id}`;
   io.rename(`${CHANGES_DIR}/${id}`, archiveDir);
 
+  if (noCommit) return { target, archiveDir, warnings, commitSubject: '' };
   git.run(['add', '-A']);
   const commitSubject = `archive(sdd): ${id}`;
   git.run(['commit', '-m', commitSubject]);
   return { target, archiveDir, warnings, commitSubject };
 }
 
+export interface ArchiveChangeResult {
+  result: FinalizeResult;
+}
+
+/** `change archive`: independent seal-off with task + strict git gates (r39/r40). */
+export function archiveChange(
+  git: GitLike,
+  io: FsIo,
+  id: string,
+  opts: {
+    into?: string;
+    method?: 'squash' | 'ff';
+    force?: boolean;
+    minCompletionRatio?: number;
+    today?: string;
+  } = {},
+): FinalizeResult {
+  const path = proposalPath(id);
+  const binding = readBinding(io.readText(path));
+  if (!opts.force && binding === null) {
+    throw new LifecycleError(`change \`${id}\` has no branch binding — run start/attach first`);
+  }
+  if (!opts.force) {
+    const tasksPath = `${CHANGES_DIR}/${id}/tasks.md`;
+    const gate = archiveTaskGate(
+      io.exists(tasksPath) ? io.readText(tasksPath) : null,
+      opts.minCompletionRatio,
+    );
+    if (gate.blocked) throw new LifecycleError(gate.reasons.join('\n'));
+    const current = currentBranch(git);
+    if (current === null || current === '')
+      throw new LifecycleError('detached HEAD — cannot archive');
+    if (current !== binding?.branch) {
+      throw new LifecycleError(
+        `archive must run on attached branch \`${binding?.branch}\` (current: \`${current}\`)`,
+      );
+    }
+    if (current === defaultBranch(git)) {
+      throw new LifecycleError('archive must not run on the default branch');
+    }
+    if (!isCleanTree(git)) throw new LifecycleError('working tree must be clean to archive');
+  } else if (binding === null) {
+    throw new LifecycleError(`change \`${id}\` has no branch binding — cannot merge`);
+  }
+  const method = opts.method ?? 'squash';
+  const target = opts.into ?? binding?.baseBranch ?? defaultBranch(git);
+  return mergeRenameCommit(git, io, id, binding?.branch as string, target, method, opts.today);
+}
+
 /** `change diff <id>`: full diff of the bound branch vs base. */
 export function changeDiff(git: GitLike, io: FsIo, id: string): string {
   const binding = readBinding(io.readText(proposalPath(id)));
@@ -139,3 +286,19 @@ export function changeDiff(git: GitLike, io: FsIo, id: string): string {
   const base = binding.baseBranch ?? defaultBranch(git);
   return git.run(['diff', `${base}...${binding.branch}`]);
 }
+
+export interface ChangeDiffInfo {
+  change: string;
+  branch: string;
+  base: string;
+  commitCount: number;
+}
+
+/** `change diff --json` (r46): structured bound-branch summary. */
+export function changeDiffInfo(git: GitLike, io: FsIo, id: string): ChangeDiffInfo {
+  const binding = readBinding(io.readText(proposalPath(id)));
+  if (binding === null) throw new LifecycleError(`change \`${id}\` has no branch binding`);
+  const count =
+    git.runOpt(['rev-list', '--count', `${binding.baseSha}...${binding.branch}`]) ?? '0';
+  return { change: id, branch: binding.branch, base: binding.baseSha, commitCount: Number(count) };
+}

package/src/change/nextId.ts

@@ -0,0 +1,55 @@
+/**
+ * Whole-tree change-id number harvest (r35, v1 `change next-id` parity).
+ * Read-only: walks directory names at any depth under `llmanspec/` and
+ * extracts `c<digits>` tokens at token boundaries — the same value
+ * `change new --from` used to inject as `llman_sdd_unique_id`.
+ */
+
+export interface NextIdIo {
+  listDir(path: string): string[];
+  isDirectory(path: string): boolean;
+}
+
+export interface IdHarvest {
+  maxNumber: number | null;
+  nextNumber: number;
+  warnings: string[];
+}
+
+const C_TOKEN_RE = /(?:^|[^a-z0-9])c([0-9]+)(?:$|[^a-z0-9])/iu;
+
+/**
+ * Extract the number carried by a change-id-shaped directory name: the first
+ * `c<digits>` run at a token boundary (matches `c2790`, `c10-active`, and the
+ * `2026-01-01-c20-slug` date-prefixed archive shape; glued names like `cab12`
+ * match no position). Leading digits (`3-third`) do not count.
+ */
+export function extractUniqueNumber(name: string): number | null {
+  const m = C_TOKEN_RE.exec(name);
+  return m ? Number(m[1]) : null;
+}
+
+export function harvestUniqueNumbers(io: NextIdIo, root: string): IdHarvest {
+  const numbers: number[] = [];
+  const warnings: string[] = [];
+  const walk = (dir: string): void => {
+    let names: string[];
+    try {
+      names = io.listDir(dir);
+    } catch (error) {
+      warnings.push(`cannot list ${dir}: ${(error as Error).message}`);
+      return;
+    }
+    for (const name of names.toSorted()) {
+      if (name.startsWith('.')) continue;
+      const full = `${dir}/${name}`;
+      if (!io.isDirectory(full)) continue;
+      const n = extractUniqueNumber(name);
+      if (n !== null) numbers.push(n);
+      walk(full);
+    }
+  };
+  walk(root);
+  const maxNumber = numbers.length > 0 ? Math.max(...numbers) : null;
+  return { maxNumber, nextNumber: maxNumber === null ? 1 : maxNumber + 1, warnings };
+}

package/src/change/resolve.ts

@@ -0,0 +1,34 @@
+/**
+ * Change-id prefix resolution (peripheral-commands r61, v1 cli spec r112):
+ * exact match > unique prefix > multiple candidates > no match, all
+ * case-sensitive. Candidates are the active change ids discovered via
+ * collectChanges (depth-limited, archive-skipping). Pure — IO is injected.
+ */
+import { collectChanges, type ChangeFsIo } from '../report/collect.ts';
+
+export interface ResolvedChangeId {
+  id: string;
+  viaPrefix: boolean;
+}
+
+export class ChangeIdResolveError extends Error {}
+
+export function resolveChangeId(
+  io: ChangeFsIo,
+  root: string,
+  input: string,
+  opts: { maxScanDepth?: number } = {},
+): ResolvedChangeId {
+  const ids = collectChanges(io, root, new Date(0), opts).map((c) => c.name);
+  if (ids.includes(input)) return { id: input, viaPrefix: false };
+  const matches = ids.filter((id) => id.startsWith(input));
+  if (matches.length === 1) return { id: matches[0] as string, viaPrefix: true };
+  if (matches.length > 1) {
+    throw new ChangeIdResolveError(
+      `change '${input}' matches multiple active changes:\n${matches
+        .map((m) => `  - ${m}`)
+        .join('\n')}\nDid you mean one of these?`,
+    );
+  }
+  throw new ChangeIdResolveError(`change not found: ${input}`);
+}

package/src/config/changeId.ts

@@ -0,0 +1,87 @@
+/**
+ * change_id contract (r59/r60): pattern compile-check at load time, validate
+ * ERROR for active changes violating the pattern, and `change new --from`
+ * template rendering (nunjucks Strict) with the v1 preset variables.
+ */
+
+import nunjucks from 'nunjucks';
+
+import { harvestUniqueNumbers, type NextIdIo } from '../change/nextId.ts';
+
+export class ChangeIdError extends Error {}
+
+/** Compile-check a configured change_id.pattern (r59). */
+export function compileChangeIdPattern(pattern: string | null | undefined): RegExp | null {
+  if (pattern === null || pattern === undefined || pattern === '') return null;
+  try {
+    return new RegExp(pattern, 'u');
+  } catch (error) {
+    throw new ChangeIdError(`change_id.pattern is not a valid regex: ${(error as Error).message}`);
+  }
+}
+
+export interface ChangeIdVars {
+  /** whole-tree next free number (v1 llman_sdd_unique_id) */
+  llman_sdd_unique_id: number;
+  /** explicit --verb value; undefined when not provided (Strict render errors) */
+  verb?: string;
+  /** slugified description subject */
+  subject: string;
+  /** YYYY-MM-DD */
+  date: string;
+}
+
+/**
+ * Render a change_id.template with v1 preset vars (r60). Strict semantics:
+ * referencing a variable that was not provided errors out (v1 parity —
+ * `{{ verb }}` without --verb fails).
+ */
+export function renderChangeIdTemplate(template: string, vars: ChangeIdVars): string {
+  // Named pre-check (v1 parity): referencing an unprovided variable errors with
+  // the variable name and the preset list, instead of a generic render error.
+  const provided = new Set(
+    Object.keys(vars).filter((k) => vars[k as keyof ChangeIdVars] !== undefined),
+  );
+  for (const m of template.matchAll(/\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/gu)) {
+    const name = m[1] as string;
+    if (!provided.has(name)) {
+      throw new ChangeIdError(
+        `change_id.template references unprovided variable(s): ${name} — preset vars are llman_sdd_unique_id, verb, subject, date (pass --verb when it uses {{ verb }})`,
+      );
+    }
+  }
+  const env = new nunjucks.Environment(undefined, { throwOnUndefined: true });
+  const rendered = env.renderString(template, vars as unknown as Record<string, unknown>).trim();
+  if (rendered === '') throw new ChangeIdError('change_id.template rendered to an empty id');
+  return rendered;
+}
+
+/** Whole-tree next free number for the llman_sdd_unique_id preset var. */
+export function nextUniqueNumber(io: NextIdIo, llmanspecRoot: string): number {
+  return harvestUniqueNumbers(io, llmanspecRoot).nextNumber;
+}
+
+const VERB_TABLE = ['add', 'update', 'remove', 'refactor', 'fix'] as const;
+
+/**
+ * v1 `new.rs::split_verb` parity: the subject is the derived id minus a
+ * detected table-verb prefix; the verb is the explicit override when given,
+ * otherwise the auto-detected one (v1 renders `{{ verb }}` without --verb for
+ * descriptions that carry a verb token).
+ */
+export function splitVerb(
+  derived: string,
+  verbOverride: string | undefined,
+): { verb?: string; subject: string } {
+  let subject = derived;
+  let detected: string | undefined;
+  for (const verb of VERB_TABLE) {
+    if (derived.startsWith(`${verb}-`)) {
+      detected = verb;
+      subject = derived.slice(verb.length + 1);
+      break;
+    }
+  }
+  const verb = verbOverride !== undefined ? verbOverride : detected;
+  return { verb, subject };
+}

package/src/config/surface.ts

@@ -0,0 +1,59 @@
+/**
+ * `config` command surface (r37/r38): read-only overview rendering and
+ * non-interactive extra_skills management with comment-preserving writeback.
+ */
+
+import { parseDocument } from 'yaml';
+
+import { loadConfig } from './load.ts';
+import { EXTRA_SKILLS } from './schema.ts';
+
+/** Render the five-element overview (v1 parity wording). */
+export function renderConfigOverview(source: string): string[] {
+  const config = loadConfig(source);
+  const enabled = (config.extra_skills ?? []).length;
+  const archive = config.archive;
+  const archiveConfigured =
+    archive !== null &&
+    archive !== undefined &&
+    (archive.strict_defer || archive.min_completion_ratio !== undefined);
+  return [
+    `schema: ${config.schema}`,
+    `locale: ${config.locale}`,
+    `extra_skills (enabled/total): ${enabled} / ${EXTRA_SKILLS.length}`,
+    `bdd: ${config.bdd ? 'on' : 'off'}`,
+    `archive: ${archiveConfigured ? 'configured' : 'default'}`,
+  ];
+}
+
+export class ExtraSkillsError extends Error {}
+
+/**
+ * Add/remove extra_skills entries with full comment preservation: only the
+ * `extra_skills` list node is touched, everything else (including the
+ * `$schema` header comment) stays byte-identical.
+ */
+export function setExtraSkills(
+  source: string,
+  change: { set?: readonly string[]; unset?: readonly string[] },
+): string {
+  for (const name of [...(change.set ?? []), ...(change.unset ?? [])]) {
+    if (!(EXTRA_SKILLS as readonly string[]).includes(name)) {
+      throw new ExtraSkillsError(`unknown extra skill: ${name}`);
+    }
+  }
+  const wanted = new Set<string>(loadConfig(source).extra_skills ?? []);
+  for (const name of change.set ?? []) wanted.add(name);
+  for (const name of change.unset ?? []) wanted.delete(name);
+
+  const doc = parseDocument(source);
+  const list = [...wanted].toSorted();
+  if (list.length > 0) doc.set('extra_skills', list);
+  else doc.delete('extra_skills');
+  return doc.toString();
+}
+
+/** Shape of `config skills --json` (v1 parity). */
+export function skillsJson(source: string): { enabled: string[]; available: readonly string[] } {
+  return { enabled: [...(loadConfig(source).extra_skills ?? [])], available: EXTRA_SKILLS };
+}