@starci/hfs 4.0.8 → 4.0.9

package/runtime/scripts/lib/dockerfile.mjs

@@ -0,0 +1,124 @@
+// dockerfile.mjs - a Dockerfile read by its own grammar (no regular-expression matching of instruction names inside the text):
+// one statement per logical line (a trailing backslash continues it, comment lines inside a continuation are dropped), the
+// instruction keyword is the first word, the stages open at each FROM. Parser directives (`# syntax=`, `# escape=`) and
+// comments are kept apart from the instructions. Here-documents are not part of the subset the canon uses and are read as text.
+
+/** Split a shell-form or exec-form argument string into its words (quotes group a word and are removed). */
+export function words(text) {
+  const out = [];
+  let current = '';
+  let quote = null;
+  let started = false;
+  for (const char of text) {
+    if (quote) {
+      if (char === quote) quote = null;
+      else current += char;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+      started = true;
+    } else if (char === ' ' || char === '\t' || char === '\n') {
+      if (started || current) out.push(current);
+      current = '';
+      started = false;
+    } else {
+      current += char;
+    }
+  }
+  if (started || current) out.push(current);
+  return out;
+}
+
+/** The exec-form array of an instruction's argument text (`["node", "x.js"]`), or null when it is not a JSON array of strings. */
+export function execForm(text) {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith('[')) return null;
+  try {
+    const value = JSON.parse(trimmed);
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The commands of a shell-form RUN body: the text split at `&&`, `||`, `;` and `|` outside quotes, each as its words. */
+export function shellCommands(body) {
+  const commands = [];
+  let current = '';
+  let quote = null;
+  const flush = () => {
+    const parts = words(current);
+    if (parts.length) commands.push(parts);
+    current = '';
+  };
+  for (let i = 0; i < body.length; i += 1) {
+    const char = body[i];
+    if (quote) {
+      current += char;
+      if (char === quote) quote = null;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+      current += char;
+    } else if (char === ';' || char === '|' || (char === '&' && body[i + 1] === '&')) {
+      if (char !== ';' && body[i + 1] === char) i += 1;
+      flush();
+    } else if (char === '\\' && body[i + 1] === '\n') {
+      i += 1;
+    } else {
+      current += char;
+    }
+  }
+  flush();
+  return commands;
+}
+
+/**
+ * Parse a Dockerfile: { instructions: [{ keyword, text, line, stage }], stages: [{ index, name, image, line, instructions }],
+ * comments: [{ text, line }], preamble: [instruction before the first FROM (ARG)] }. `keyword` is upper-case; `text` is the
+ * argument text of the logical line; `stage` is the index of the stage the instruction belongs to (-1 before the first FROM).
+ */
+export function parseDockerfile(source) {
+  const lines = String(source).replace(/\r\n/g, '\n').split('\n');
+  const instructions = [];
+  const comments = [];
+  let escape = '\\';
+  let directives = true;
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i];
+    const trimmed = raw.trim();
+    if (trimmed === '') { directives = false; continue; }
+    if (trimmed.startsWith('#')) {
+      const body = trimmed.slice(1).trim();
+      const directive = directives ? /^(syntax|escape|check)\s*=\s*(\S+)$/i.exec(body) : null;
+      if (directive) { if (directive[1].toLowerCase() === 'escape') escape = directive[2]; continue; }
+      directives = false;
+      comments.push({ text: body, line: i + 1 });
+      continue;
+    }
+    directives = false;
+    const start = i + 1;
+    let logical = trimmed;
+    while (logical.endsWith(escape) && i + 1 < lines.length) {
+      logical = logical.slice(0, -1).trimEnd();
+      i += 1;
+      while (i < lines.length && lines[i].trim().startsWith('#')) i += 1;
+      if (i >= lines.length) break;
+      logical = `${logical} ${lines[i].trim()}`;
+    }
+    const split = logical.search(/\s/);
+    const keyword = (split < 0 ? logical : logical.slice(0, split)).toUpperCase();
+    instructions.push({ keyword, text: split < 0 ? '' : logical.slice(split).trim(), line: start, stage: -1 });
+  }
+  const stages = [];
+  const preamble = [];
+  for (const instruction of instructions) {
+    if (instruction.keyword === 'FROM') {
+      const parts = words(instruction.text).filter((part) => !part.startsWith('--'));
+      const asAt = parts.findIndex((part, index) => index > 0 && part.toUpperCase() === 'AS');
+      stages.push({ index: stages.length, name: asAt > 0 ? parts[asAt + 1] ?? null : null, image: parts[0] ?? '', line: instruction.line, instructions: [] });
+    }
+    instruction.stage = stages.length - 1;
+    if (stages.length) stages.at(-1).instructions.push(instruction);
+    else preamble.push(instruction);
+  }
+  return { instructions, stages, comments, preamble };
+}

package/runtime/scripts/lib/env.mjs

@@ -0,0 +1,10 @@
+// env.mjs - the one place the runtime reads a named environment variable (smell S8-01/S8-02/S11-04; scripts/checks/check-env.mjs).
+// modules/schemas/env.yaml catalogues every variable with its purpose and kind. Production code reads a variable here
+// (readEnv) or takes an injected `env` parameter; it never reads `process.env.NAME` itself. The test runner is observed
+// in exactly one place, isSpecRun: code that must not touch the host's real state during a spec asks it.
+
+/** The value of the environment variable `name` in `env` (default: the process environment), or undefined. */
+export const readEnv = (name, env = process.env) => env[name];
+
+/** True when `env` (default: the process environment) belongs to a spec run (`node --test` marks its children with NODE_TEST_CONTEXT). */
+export const isSpecRun = (env = process.env) => Boolean(env.NODE_TEST_CONTEXT);

package/runtime/scripts/lib/event-contract.mjs

@@ -0,0 +1,103 @@
+// event-contract.mjs - the async contract between the services of one product (R166 HFS_EVENT_CONTRACT).
+// The one source of the contract is the typed event classes of a service, `be/src/modules/events/<service>/<event>.event.ts`:
+//   export interface OrderPlacedPayload { readonly orderId: string; readonly totalMinorUnits: number }
+//   export class OrderPlacedEvent extends BaseEvent {
+//     static readonly eventName = "order.placed"; static readonly version = 1
+//     static readonly compensates = "order.placed"            // only an event that reports the failure of a step
+//     static create(payload: OrderPlacedPayload): OrderPlacedEvent { ... }
+//   }
+// `starci app emit` writes `be/contracts/<service>/events.json` from them (name, version, compensates, and the payload fields of the
+// interface `create` takes); `starci app check` compares the committed file with the same reader. Nothing is executed: both walk the TypeScript
+// syntax tree. The functions take the `ts` module the caller loaded (the repository's own, else the runtime's); this file imports nothing.
+
+const EVENT_CONTRACT_SCHEMA = 'starci/event-contract@1';
+const FIELD_TYPE = /^(?:string|number|boolean|string\[\]|number\[\])\??$/;
+
+const hasStatic = (ts, member) => member.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.StaticKeyword) === true;
+
+/** The literal of a `static readonly <name> = <literal>` member: `{ text }` for a string, `{ number }` for an integer, or null. */
+function staticLiteral(ts, member) {
+  if (!ts.isPropertyDeclaration(member) || !hasStatic(ts, member) || !ts.isIdentifier(member.name) || member.initializer === undefined) return null;
+  let value = member.initializer;
+  while (ts.isAsExpression(value) || ts.isParenthesizedExpression(value)) value = value.expression;
+  if (ts.isStringLiteralLike(value)) return { name: member.name.text, text: value.text };
+  if (ts.isNumericLiteral(value) && Number.isInteger(Number(value.text))) return { name: member.name.text, number: Number(value.text) };
+  return null;
+}
+
+/** The text of a type node when it is one of the wire field types (`string`, `number`, `boolean`, `string[]`, `number[]`), else null. */
+function fieldType(ts, node) {
+  if (node.kind === ts.SyntaxKind.StringKeyword) return 'string';
+  if (node.kind === ts.SyntaxKind.NumberKeyword) return 'number';
+  if (node.kind === ts.SyntaxKind.BooleanKeyword) return 'boolean';
+  if (ts.isArrayTypeNode(node)) {
+    const element = fieldType(ts, node.elementType);
+    return element === 'string' || element === 'number' ? `${element}[]` : null;
+  }
+  return null;
+}
+
+/** The payload fields of the interface or type literal named `typeName` in the file: `{ <field>: <type> }`, optional fields with a `?`. */
+function payloadOf(ts, sourceFile, typeName, problems, where) {
+  let members = null;
+  for (const statement of sourceFile.statements) {
+    if (ts.isInterfaceDeclaration(statement) && statement.name.text === typeName) members = statement.members;
+    if (ts.isTypeAliasDeclaration(statement) && statement.name.text === typeName && ts.isTypeLiteralNode(statement.type)) members = statement.type.members;
+  }
+  if (members === null) {
+    problems.push(`${where}: the payload type ${typeName} is not an interface or type literal of the file`);
+    return {};
+  }
+  const payload = {};
+  for (const member of members) {
+    if (!ts.isPropertySignature(member) || !ts.isIdentifier(member.name) || member.type === undefined) {
+      problems.push(`${where}: the payload ${typeName} holds a member that is not \`name: type\``);
+      continue;
+    }
+    const type = fieldType(ts, member.type);
+    const written = type === null ? null : `${type}${member.questionToken ? '?' : ''}`;
+    if (written === null || !FIELD_TYPE.test(written)) problems.push(`${where}: payload field ${member.name.text} must be string, number, boolean, string[] or number[]`);
+    else payload[member.name.text] = written;
+  }
+  return payload;
+}
+
+/**
+ * The event classes of one source text: `{ events: [{ className, name, version, compensates, payload }], problems: [text] }`. A class is an event
+ * when it declares `static readonly eventName`; `version` is required, `create(payload: <Interface>)` names the payload.
+ */
+export function readEventClasses(ts, text, file = 'event.ts') {
+  const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const events = [];
+  const problems = [];
+  for (const statement of sourceFile.statements) {
+    if (!ts.isClassDeclaration(statement) || statement.name === undefined) continue;
+    const literals = statement.members.map((member) => staticLiteral(ts, member)).filter((literal) => literal !== null);
+    const name = literals.find((literal) => literal.name === 'eventName')?.text;
+    if (name === undefined) continue;
+    const className = statement.name.text;
+    const version = literals.find((literal) => literal.name === 'version')?.number;
+    const compensates = literals.find((literal) => literal.name === 'compensates')?.text;
+    if (version === undefined || version < 1) problems.push(`${className} needs \`static readonly version\` as a positive integer`);
+    const create = statement.members.find((member) => ts.isMethodDeclaration(member) && hasStatic(ts, member) && ts.isIdentifier(member.name) && member.name.text === 'create');
+    const parameter = create?.parameters[0]?.type;
+    if (parameter === undefined || !ts.isTypeReferenceNode(parameter) || !ts.isIdentifier(parameter.typeName)) {
+      problems.push(`${className} needs \`static create(payload: <Interface>)\` naming its payload interface`);
+      continue;
+    }
+    events.push({ className, name, version: version ?? 0, ...(compensates === undefined ? {} : { compensates }), payload: payloadOf(ts, sourceFile, parameter.typeName.text, problems, className) });
+  }
+  return { events, problems };
+}
+
+/** The sorted object: keys in code-point order, recursively (what the snapshot prints). */
+const sorted = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, sorted(value[key])])) : value);
+
+/** The text of the snapshot of a service from its event classes: 2-space JSON, sorted keys, one final newline. */
+export function snapshotText(service, events) {
+  const table = Object.fromEntries(events.map(({ name, version, compensates, payload }) => [name, { version, payload, ...(compensates === undefined ? {} : { compensates }) }]));
+  return `${JSON.stringify(sorted({ schema: EVENT_CONTRACT_SCHEMA, service, events: table }), null, 2)}\n`;
+}
+
+/** The snapshot's text with line endings folded, for comparing a committed file to a fresh one. */
+export const folded = (text) => text.replace(/\r\n/g, '\n');

package/runtime/scripts/lib/git.mjs

@@ -0,0 +1,36 @@
+// git.mjs — pure helpers over git's text output, spawn results and env. The git spawn itself lives in scripts/api/git/ (lib.mjs and its call files).
+
+/**
+ * git's C-quoted diff path decoded - `"b\303\251"` a `+++ ` header line prints when core.quotePath
+ * covers the name. Octal escapes become \u00XX for JSON.parse (which answers \n, \t, \" and \\);
+ * a value not wrapped in quotes passes through unchanged.
+ */
+export const unquoteDiffPath = (value) =>
+  /^".*"$/.test(value)
+    ? JSON.parse(value.replace(/\\([0-7]{3})/g, (_, octal) => `\\u00${Number.parseInt(octal, 8).toString(16).padStart(2, '0')}`))
+    : value;
+
+// git's repository-local variables (git rev-parse --local-env-vars). A hook or alias run in a linked worktree exports
+// GIT_DIR=<main>/.git/worktrees/<wt>; a spec inheriting it pointed every fixture git at the LIVE .claude repo and re-inited
+// it core.bare=true (2026-09-29, a6f60352c). tests/setup/isolated-registry.mjs drops the same list.
+export const GIT_LOCAL_ENV_VARS = ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_IMPLICIT_WORK_TREE', 'GIT_PREFIX', 'GIT_CONFIG', 'GIT_CONFIG_PARAMETERS', 'GIT_CONFIG_COUNT', 'GIT_GRAFT_FILE', 'GIT_NO_REPLACE_OBJECTS', 'GIT_REPLACE_REF_BASE', 'GIT_SHALLOW_FILE'];
+/** `parent` (the caller's env) without git's repository-local variables (GIT_CONFIG_KEY_n/VALUE_n go with GIT_CONFIG_COUNT). Pure. */
+export function withoutGitLocalEnv(parent) {
+  const env = { ...parent };
+  for (const key of Object.keys(env)) if (GIT_LOCAL_ENV_VARS.includes(key) || /^GIT_CONFIG_(KEY|VALUE)_\d+$/.test(key)) delete env[key];
+  return env;
+}
+
+/** A git spawn result (a scripts/api/git call file's) as {ok, stdout, error}: ok only on a clean exit, error from stderr or the spawn. Pure. */
+export const gitResultOf = (r) => ({
+  ok: !r.error && r.status === 0,
+  stdout: r.stdout ?? '',
+  error: (r.stderr ?? '').trim() || String(r.error?.message ?? (r.status == null ? 'timed out' : `exit ${r.status}`)),
+});
+
+/** A git spawn result's stdout text; throws the spawn error, or an Error naming `what` with git's stderr and exit status, unless git exited 0. Pure. */
+export function gitOutputOf(r, what = 'git') {
+  if (r.error) throw r.error;
+  if (r.status !== 0) throw Object.assign(new Error(`${what} exited ${r.status}: ${(r.stderr ?? '').trim()}`), { status: r.status, stderr: r.stderr });
+  return r.stdout;
+}

package/runtime/scripts/lib/graphql-contract.mjs

@@ -1,5 +1,5 @@
 // graphql-contract.mjs - the GraphQL a back-end contract snapshot holds and the checks a front-end document must pass
-// against it. It reads the SDL `hfs emit-contracts` writes (`be/contracts/<service>/schema.graphql`: object, input, enum,
+// against it. It reads the SDL `starci app emit` writes (`be/contracts/<service>/schema.graphql`: object, input, enum,
 // scalar, interface and union types, descriptions and directives) and the executable documents a front end keeps in
 // `.graphql` files (operations with variables, field arguments, object literals, inline fragments), with no dependency:
 // the runtime ships no GraphQL library, and an app's own install is not always resolvable from where hfs runs.

package/runtime/scripts/lib/i18n.mjs

@@ -0,0 +1,86 @@
+// i18n.mjs - the ONE mechanism for text the owner must read in Vietnamese. Runtime source, comments and messages are English;
+// a message the owner reads (a Telegram notice, a why line, a progress report) is written once in English at its call site and
+// translated through a DECLARED catalog keyed from that English source: modules/i18n/messages/<area>.yaml, a list of
+// `{en, vi}` entries. Each area belongs to a scope: `runtime` for Node callers or `ui` for the generated browser catalog.
+// The `vi` field is declared in scripts/lib/language.mjs, so it is the only Vietnamese source. There is no per-module
+// `TEXT.vi` table and no second catalog mechanism.
+//
+//   const tr = translator(config.language);      // 'vi' translates, anything else returns the English source
+//   tr('Workflow {id} needs your decision', { id })
+//
+// A placeholder is `{name}`; the English and the Vietnamese of one entry carry exactly the same placeholders
+// (scripts/checks/check-i18n-catalog.mjs). An English source with no entry is returned as is: a missing translation degrades
+// to English, never to a blank.
+import { escapeRegExp } from './regex.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { DEFAULT_OWNER_LANGUAGE, loadConfig } from '../../engine/config.mjs';
+
+export const CATALOG_DIR = 'modules/i18n/messages';
+export const PLACEHOLDER = /\{([A-Za-z_][\w]*)\}/g;
+
+const cache = new Map();
+
+/** The catalog files of a runtime root: repository-relative paths, sorted. */
+export function catalogFiles(root = skillRoot) {
+  const dir = path.join(root, ...CATALOG_DIR.split('/'));
+  try { return fs.readdirSync(dir).filter((name) => /\.ya?ml$/.test(name)).sort().map((name) => `${CATALOG_DIR}/${name}`); } catch { return []; }
+}
+
+/** Every entry in one catalog scope: `[{ en, vi, area, scope, file }]`. */
+export function catalogEntries(root = skillRoot, { scope = 'runtime' } = {}) {
+  return catalogFiles(root).flatMap((rel) => {
+    const doc = parseYaml(fs.readFileSync(path.join(root, ...rel.split('/')), 'utf8'));
+    const documentScope = typeof doc?.scope === 'string' ? doc.scope : 'runtime';
+    if (documentScope !== scope) return [];
+    return (Array.isArray(doc?.messages) ? doc.messages : []).map((entry) => ({
+      en: entry?.en, vi: entry?.vi, area: doc?.area, scope: documentScope, file: rel,
+    }));
+  });
+}
+
+/** One scoped catalog as a Map from the English source to the Vietnamese text (cached per root and scope). */
+export function loadCatalog(root = skillRoot, { scope = 'runtime' } = {}) {
+  const key = `${root}\0${scope}`;
+  if (!cache.has(key)) cache.set(key, new Map(catalogEntries(root, { scope }).filter((e) => typeof e.en === 'string' && typeof e.vi === 'string').map((e) => [e.en, e.vi])));
+  return cache.get(key);
+}
+
+/** Forget the cached catalogs (a spec that rewrites a catalog file). */
+export const resetCatalogCache = () => cache.clear();
+
+/** The names each `pattern` match captures (group 1) in `text`, in match order (`sort` sorts them). */
+export const captureNames = (text, pattern, { sort = false } = {}) => {
+  const names = [...String(text).matchAll(pattern)].map((m) => m[1]);
+  return sort ? names.sort() : names;
+};
+
+/** The names of the placeholders of a message. */
+export const placeholdersOf = (text) => captureNames(text, PLACEHOLDER, { sort: true });
+
+/** `text` with each `{name}` replaced by vars[name] (an unknown name is left as written). */
+export const fill = (text, vars = {}) => String(text).replace(PLACEHOLDER, (whole, name) => (Object.hasOwn(vars, name) ? String(vars[name]) : whole));
+
+/** The message `en` in `language` (`vi` translates through the catalog; any other language is the English source). */
+export function translate(en, vars = {}, { language = DEFAULT_OWNER_LANGUAGE, root = skillRoot, scope = 'runtime' } = {}) {
+  const vi = language === 'vi' ? loadCatalog(root, { scope }).get(en) : undefined;
+  return fill(vi ?? en, vars);
+}
+
+/** The owner's language (config.yaml `language`); `fallback` when there is no readable config (DEFAULT_OWNER_LANGUAGE of engine/config.mjs). */
+export function ownerLanguage(fallback = DEFAULT_OWNER_LANGUAGE) {
+  try { return loadConfig()?.language ?? fallback; } catch { return fallback; }
+}
+
+/** A translator bound to one language: `tr(en, vars)`. */
+export const translator = (language = DEFAULT_OWNER_LANGUAGE, { root = skillRoot, scope = 'runtime' } = {}) =>
+  (en, vars = {}) => translate(en, vars, { language, root, scope });
+
+/**
+ * A pattern source matching `en` in the owner's language or in English: each language's rendering of the English source,
+ * escaped, with the placeholder `slot` (a placeholder name of `en`) replaced by `slotPattern`. Never hardcodes a spelling.
+ */
+export const translatedPattern = (en, slot, slotPattern, languages = ['en', 'vi']) =>
+  `(?:${languages.map((language) => escapeRegExp(translate(en, { [slot]: '@@' }, { language })).replace('@@', slotPattern)).join('|')})`;

package/runtime/scripts/lib/json.mjs

@@ -1,7 +1,7 @@
 // json.mjs — the ledger's forgiving JSON read. Every one of these rows may hold text a peer wrote or a
 // truncated payload, so a malformed column is the caller's fallback, never a throw. The parse of the
 // literal 'null' is kept as null (callers that want {} instead write `parseJsonOr`).
-import fs from 'node:fs';
+import { readParsedFile } from './read-text.mjs';
 
 /** `text` as JSON, or `fallback` when it does not parse. */
 export const parseJson = (text, fallback = null) => {
@@ -17,6 +17,16 @@ export const parseJsonOr = (text, fallback = {}) => parseJson(text) ?? fallback;
 export const withPayload = (row, fallback = {}) => (row ? { ...row, payload: parseJsonOr(row.payload_json, fallback) } : row);
 
 /** `file` read and parsed as JSON, or `fallback` when the file is missing, unreadable or malformed. */
-export const readJsonFile = (file, fallback = null) => {
-  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+export const readJsonFile = (file, fallback = null) => readParsedFile(file, JSON.parse, fallback);
+
+/** `stdout` as JSON: the trimmed text, else its first-{-to-last-} span; null when neither parses. */
+export const jsonFromStdout = (stdout) => {
+  const text = String(stdout ?? '').trim();
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { /* fall through */ }
+  const first = text.indexOf('{'), last = text.lastIndexOf('}');
+  if (first >= 0 && last > first) {
+    try { return JSON.parse(text.slice(first, last + 1)); } catch { /* not json */ }
+  }
+  return null;
 };

package/runtime/scripts/lib/language.mjs

@@ -39,6 +39,8 @@ export const FAILURE_CODE_VIETNAMESE_FIELDS = Object.freeze(['title_vi', 'meanin
  *  - modules/ops/_labels.yaml: the op-label catalogue, one `{ vi, en }` pair per op (the `vi` field is the localized label).
  *  - modules/goal/archetypes.yaml: the Vietnamese phrase lexicons matched against owner input (the signal phrase sets, and the
  *    phrase lists of the archetype recognisers).
+ *  - modules/goal/source-phrases.yaml: the Vietnamese phrase lists runtime source matchers read through
+ *    scripts/lib/source-phrases.mjs (owner replies, report wording, product copy) - each leaf list under `phrases`.
  * An op manifest (modules/ops/ops/<id>.yaml, the starci/op@1 documents check-op-manifest types) is declared by
  * OP_MANIFEST_VIETNAMESE_FIELDS: its text objects are {en, vi} (modules/schemas/op.schema.yaml $defs text), and `vi` is the
  * owner's reading of the same rule.
@@ -52,13 +54,30 @@ export const DECLARED_VIETNAMESE_FIELDS = Object.freeze({
       'phrases', 'requires', 'excludes', 'backend', 'frontend', 'package',
     ]),
   }),
+  'modules/goal/source-phrases.yaml': Object.freeze({
+    fields: Object.freeze([
+      'prefer', 'avoid', 'negation', 'refused', 'accept', 'golden',
+      'missingPaths', 'grantTooNarrow', 'toolTimeout', 'testGap', 'checkerUnavailable',
+      'supervisorVerbs', 'ownerWord', 'orWord', 'beyondAuthority', 'ownerOnly', 'workerDied', 'contractConflict', 'decision',
+      'product', 'grammar', 'knowledge', 'sourceLabel', 'internalVocabulary', 'actor', 'success',
+      'wizard', 'form', 'dashboard', 'gap', 'anatomy', 'otpLabel',
+    ]),
+  }),
 });
 
+/**
+ * The Vietnamese catalog of owner-visible messages (scripts/lib/i18n.mjs): modules/i18n/messages/<area>.yaml, a list of
+ * `{en, vi}` entries keyed from the English source. The `vi` field (block or inline flow) is the declared Vietnamese.
+ */
+const I18N_CATALOG_VIETNAMESE_FIELDS = Object.freeze({ fields: Object.freeze(['vi']), flowFields: Object.freeze(['vi']) });
+const I18N_CATALOG_DIR = 'modules/i18n/messages/';
+
 /** The `vi` field of an op manifest's text objects (modules/schemas/op.schema.yaml $defs text). */
-export const OP_MANIFEST_VIETNAMESE_FIELDS = Object.freeze({ fields: Object.freeze(['vi']) });
+const OP_MANIFEST_VIETNAMESE_FIELDS = Object.freeze({ fields: Object.freeze(['vi']) });
 const OP_MANIFEST_DIR = 'modules/ops/ops/';
 /** The declared Vietnamese fields of `rel`: its own entry, or the op-manifest text field for a manifest of modules/ops/ops. */
 export const declaredVietnameseFieldsOf = (rel) => DECLARED_VIETNAMESE_FIELDS[rel]
+  ?? (rel.startsWith(I18N_CATALOG_DIR) && !rel.slice(I18N_CATALOG_DIR.length).includes('/') && /\.ya?ml$/.test(rel) ? I18N_CATALOG_VIETNAMESE_FIELDS : null)
   ?? (rel.startsWith(OP_MANIFEST_DIR) && !rel.slice(OP_MANIFEST_DIR.length).includes('/') && /\.ya?ml$/.test(rel) ? OP_MANIFEST_VIETNAMESE_FIELDS : null);
 
 /**
@@ -66,7 +85,7 @@ export const declaredVietnameseFieldsOf = (rel) => DECLARED_VIETNAMESE_FIELDS[re
  * fixture reproduces a real localized string a parser or formatter must accept. Placement is the whole marker - there is no
  * comment pragma and no path pattern. The slots are declared in knowledge/hfs/slots.yaml.
  */
-export const LOCALIZED_TEXT_SLOTS = Object.freeze([
+const LOCALIZED_TEXT_SLOTS = Object.freeze([
   'be.domain.messages', 'be.feature.messages', 'be.tests.fixtures.i18n',
   'fe.modules.i18n', 'fe.package.i18n',
 ]);
@@ -78,7 +97,7 @@ export const isLocalizedDataFile = (rel, slot) => LOCALIZED_TEXT_SLOTS.includes(
  * The key each line of a YAML text belongs to: a `key:` line owns itself, and every deeper-indented line after it (a list item,
  * a folded block, a wrapped scalar) belongs to the same key. A line at or above the key's indent that is not a key belongs to none.
  */
-export function yamlKeyOfEachLine(text) {
+function yamlKeyOfEachLine(text) {
   let key = null;
   let keyIndent = -1;
   return String(text).split(/\r?\n/).map((raw) => {
@@ -105,13 +124,13 @@ export function documentLanguageHits(rel, text) {
     if (declared.fields?.includes(keys[hit.line - 1])) return false;
     if (!declared.flowFields) return true;
     // an inline flow map: drop the declared fields' values and judge what is left of the line
-    const rest = declared.flowFields.reduce((line, field) => line.replace(new RegExp(`\\b${field}\\s*:\\s*[^,}]*`, 'g'), ''), lines[hit.line - 1]);
+    const rest = declared.flowFields.reduce((line, field) => line.replace(new RegExp(`\\b${field}\\s*:\\s*(?:"(?:[^"\\\\]|\\\\.)*"|'(?:[^'\\\\]|\\\\.)*'|[^,}]*)`, 'g'), ''), lines[hit.line - 1]);
     return hasSecondLanguage(rest);
   });
 }
 
 /** The file extensions of a prose document (Markdown and YAML). */
-export const DOCUMENT_EXTENSIONS = Object.freeze(['.md', '.yaml', '.yml']);
+const DOCUMENT_EXTENSIONS = Object.freeze(['.md', '.yaml', '.yml']);
 
 /** Whether `rel` is a document a language check reads. */
 export const isDocument = (rel) => DOCUMENT_EXTENSIONS.includes(path.posix.extname(rel));

package/runtime/scripts/lib/list.mjs

@@ -0,0 +1,20 @@
+// list.mjs — the array-or-empty coercion half the scripts re-declared by hand.
+// `v` when it already is an array, else []. Scalars are NOT wrapped: a caller that wants
+// `[v]` for a lone value writes its own coercion (see contract-version's list).
+export const list = (v) => (Array.isArray(v) ? v : []);
+
+/** `v` as an array: itself when already one, [] for null/undefined, else [v]. */
+export const asList = (v) => (Array.isArray(v) ? v : v == null ? [] : [v]);
+
+/** The object entries of `v` (a non-array reads as []). */
+export const objectList = (v) => (Array.isArray(v) ? v : []).filter((item) => item && typeof item === 'object');
+
+/** Every entry of `v` a non-empty string (`blank: false` also rejects all-whitespace entries). */
+export const stringList = (v, { blank = true } = {}) =>
+  Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0 && (blank || s.trim().length > 0));
+
+/** The items of a `sep`-separated list: trimmed, empties dropped; `dedupe` keeps first occurrences only. */
+export const splitList = (v, { sep = ',', dedupe = false } = {}) => {
+  const items = String(v ?? '').split(sep).map((s) => s.trim()).filter(Boolean);
+  return dedupe ? [...new Set(items)] : items;
+};

package/runtime/scripts/lib/package-at.mjs

@@ -1,13 +1,32 @@
 // scripts/lib/package-at.mjs — a package the runtime does not ship (playwright, esbuild, tailwindcss) comes from the
 // project that owns it: node resolution from that project's directory, walking up its node_modules.
+import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { skillRoot } from '../../engine/runtime-root.mjs';
 
 /** The package.json of `name` as resolved from `dir`, or null. */
 export const packageAt = (dir, name) => {
   try { return createRequire(path.join(dir, 'package.json')).resolve(`${name}/package.json`); } catch { return null; }
 };
 
+/** This runtime's own `starci` bin (packages/cli is the only package that declares one). */
+const RUNTIME_STARCI_BIN = path.join(skillRoot, 'packages', 'cli', 'bin', 'starci.mjs');
+
+/** The `starci` bin of the @starci/cli that `dir` installs (a product runs its own pinned CLI), else this runtime's own. */
+export function starciBin(dir) {
+  const packageFile = packageAt(dir, '@starci/cli');
+  if (packageFile) {
+    try {
+      const { bin } = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+      const rel = typeof bin === 'string' ? bin : bin?.starci;
+      const file = rel ? path.join(path.dirname(packageFile), rel) : null;
+      if (file && fs.existsSync(file)) return file;
+    } catch { /* an unreadable install falls back to the runtime's own CLI */ }
+  }
+  return RUNTIME_STARCI_BIN;
+}
+
 /** The first of `names` resolvable from the first of `dirs` that has one: {name, root, packageFile, version} or null. */
 export function findPackage(dirs, names) {
   for (const dir of dirs.filter(Boolean)) {
@@ -23,3 +42,21 @@ export function findPackage(dirs, names) {
 
 /** The CommonJS entry of a package found by findPackage. */
 export const requirePackage = (found) => createRequire(found.packageFile)(found.name);
+
+/** The TypeScript compiler resolvable from the first of `dirs` (an app root, then the caller's own), or null. */
+export const loadTypescript = (...dirs) => {
+  const located = findPackage(dirs, ['typescript']);
+  return located ? requirePackage(located) : null;
+};
+
+/**
+ * The app's command line and the app implementation behind it: `bin` the `starci` bin of the app's installed @starci/cli, else
+ * this runtime's packages/cli/bin/starci.mjs (starciBin); `dir` the @starci/hfs that answers
+ * `starci app` - the app's own install, else the one beside its @starci/cli, else this runtime's packages/hfs - whose runtime
+ * slice the gate's base lint (scripts/gates/gate.mjs) and the READ digest (scripts/gates/read-digest.mjs) load in-process.
+ */
+export function hfsEntry(root) {
+  const cli = packageAt(root, '@starci/cli');
+  const manifest = packageAt(root, '@starci/hfs') ?? (cli && packageAt(path.dirname(cli), '@starci/hfs'));
+  return { dir: manifest ? path.dirname(manifest) : path.join(skillRoot, 'packages', 'hfs'), bin: starciBin(root) };
+}

package/runtime/scripts/lib/path-key.mjs

@@ -1,4 +1,5 @@
 // path-key.mjs — spelling and comparing paths the way this host's filesystem does.
+import fs from 'node:fs';
 import path from 'node:path';
 
 const WIN = process.platform === 'win32';
@@ -13,7 +14,61 @@ export const sameOrUnder = (file, prefix) => file === prefix || file.startsWith(
 export const foldCase = (p) => (WIN ? p.toLowerCase() : p);
 /** Whether two spellings name the same path on this host's filesystem. */
 export const samePath = (a, b) => foldCase(a) === foldCase(b);
-/** A path's comparable identity: absolute, forward slashes, no trailing slash, case-folded on Windows. */
-export const pathKey = (p) => foldCase(slash(path.resolve(p)).replace(/\/+$/, ''));
+/**
+ * A path's comparable identity: absolute, forward slashes, no trailing slash, case-folded on Windows.
+ * `fold: true` folds case on every platform (a comparison against a lowercase-stored root needs it).
+ */
+export const pathKey = (p, { fold = WIN } = {}) => {
+  const key = slash(path.resolve(p)).replace(/\/+$/, '');
+  return fold ? key.toLowerCase() : key;
+};
+/** `a` is `b` or under it, or the reverse: two path spellings whose trees touch. */
+export const pathsOverlap = (a, b) => sameOrUnder(a, b) || sameOrUnder(b, a);
+/**
+ * A path-ish string in compare form, options in spelling order:
+ * `trim` blanks at the ends, `collapse` folds '//' runs to '/', `dot` drops a leading './',
+ * `glob` strips a trailing glob ('star': '*'/'**' with their slash, 'double': a '/**' only),
+ * `fold` lowercases. A trailing '/' always goes. Null reads as ''.
+ */
+export const normPath = (p, { trim = false, collapse = false, dot = false, glob = null, fold = false } = {}) => {
+  let s = String(p ?? '');
+  if (trim) s = s.trim();
+  s = slash(s);
+  if (collapse) s = s.replace(/\/{2,}/g, '/');
+  if (dot) s = s.replace(/^\.\//, '');
+  if (glob === 'star') s = s.replace(/\/?\*+$/, '');
+  else if (glob === 'double') s = s.replace(/\/\*\*$/, '');
+  s = s.replace(/\/+$/, '');
+  return fold ? s.toLowerCase() : s;
+};
 /** A work-relative path in one spelling: forward slashes, no leading ./, no trailing slash. */
 export const normWork = (p) => String(p ?? '').trim().replaceAll('\\', '/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+
+/** `p` resolved and dereferenced (realpath where the path exists) — the canonical spelling of a checkout dir. */
+export const realPath = (p) => {
+  const resolved = path.resolve(p);
+  try { return fs.realpathSync.native(resolved); } catch { return resolved; }
+};
+/** `p` resolved and case-folded where the filesystem ignores case — the Map key of an absolute path. */
+export const resolvedKey = (p) => foldCase(path.resolve(p));
+/** Whether `a` and `b` resolve to the same path (always case-folded, so differently-cased spellings count). */
+export const sameResolvedPath = (a, b) => pathKey(a, { fold: true }) === pathKey(b, { fold: true });
+/**
+ * Whether `file` sits strictly under `root`. `key` normalizes both sides first (e.g. the registry's
+ * realpath-folded treeKey) when the callers' spellings need it.
+ */
+export const insidePath = (root, file, { key = (p) => p } = {}) => {
+  const rel = path.relative(key(root), key(file));
+  return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel);
+};
+/**
+ * A path-ish value (a string or a {path} entry) in relative compare form: trimmed, forward slashes,
+ * no trailing '/**' glob or slashes, no leading './'; `fold` lowercases for a case-insensitive key.
+ */
+export const normRel = (p, { fold = false } = {}) => {
+  const s = String(typeof p === 'string' ? p : p?.path ?? '').trim().replace(/\\/g, '/').replace(/\/\*\*$/, '').replace(/\/+$/, '').replace(/^\.\//, '');
+  return fold ? s.toLowerCase() : s;
+};
+/** Whether `file` equals or sits under one of `prefixes` (posix spellings; `dot` counts a '.' prefix as covering all). */
+export const underAny = (file, prefixes, { dot = false } = {}) =>
+  (prefixes ?? []).some((p) => (dot && p === '.') || sameOrUnder(file, p));