@starci/hfs 4.7.27 → 4.7.29

package/runtime/scripts/lib/failure-code-reads.mjs

@@ -0,0 +1,100 @@
+// failure-code-reads.mjs - the UPPER_SNAKE literals of a script that READ a value another producer made, or only describe one in a comment,
+// and so are not emitted failure codes (scripts/checks/check-failure-codes.mjs adds these quote offsets to its exact-AST exclusions).
+//   - a literal inside a comment (a name mentioned in prose is not emitted);
+//   - an operand of ===, !==, == or != against a non-literal, or a `case` label (the code is compared, not produced);
+//   - an argument of a string or collection query (endsWith, startsWith, includes, indexOf, has, get);
+//   - an element of an array literal whose only use here is `.includes(x)` / `.indexOf(x)` against a non-literal (a membership test);
+//   - the symbol half of a (symbol, package) argument pair such as `providersOf(root, 'APP_GUARD', '@nestjs/core')`: a name another package exports;
+//   - a literal the script declares as an enum member by identity (`Scalar.QUOTE_DOUBLE = "QUOTE_DOUBLE"`), wherever it then appears: the value of an enum-like constant, not a code;
+//   - the value of a property named `type` (a discriminator of someone else's API, such as a token type).
+// Emission sites (code:, reason:, finding(...), thrown messages, code lists) are never matched here. Proven by the package spec
+// src/failure-code-reads.spec.mjs over the bundled copy of this file.
+
+const EQUALITY = new Set(['===', '!==', '==', '!=']);
+const QUERY_METHODS = new Set(['endsWith', 'startsWith', 'includes', 'indexOf', 'has', 'get']);
+const MEMBERSHIP_METHODS = new Set(['includes', 'indexOf']);
+
+const isText = (t, node) => t.isStringLiteralLike(node);
+
+/** Whether `node` is the operand of an equality against a value that is not itself a literal. */
+function comparedValue(t, source, node) {
+  const parent = node.parent;
+  if (!parent || !t.isBinaryExpression(parent) || !EQUALITY.has(parent.operatorToken.getText(source))) return false;
+  const other = parent.left === node ? parent.right : parent.left;
+  return !isText(t, other);
+}
+
+/** Whether `node` is an argument of a string/collection query call such as `key.endsWith('X_Y')`. */
+function queryArgument(t, node) {
+  const call = node.parent;
+  return Boolean(call && t.isCallExpression(call) && call.arguments.includes(node)
+    && t.isPropertyAccessExpression(call.expression) && QUERY_METHODS.has(call.expression.name.text));
+}
+
+/** Whether `node` is an element of an array literal that is only tested with `.includes(value)` for a non-literal value. */
+function membershipElement(t, node) {
+  const array = node.parent;
+  if (!array || !t.isArrayLiteralExpression(array)) return false;
+  const access = array.parent;
+  if (!access || !t.isPropertyAccessExpression(access) || access.expression !== array || !MEMBERSHIP_METHODS.has(access.name.text)) return false;
+  const call = access.parent;
+  return Boolean(call && t.isCallExpression(call) && call.expression === access && call.arguments.length >= 1 && !isText(t, call.arguments[0]));
+}
+
+const PACKAGE_SPECIFIER = /^(?:@[\w.-]+\/[\w.-]+(?:\/[\w./-]+)?|\.{1,2}\/[\w./-]+)$/;
+
+/** Whether `node` is a call argument directly followed by a package or relative module specifier: the name of a symbol that module exports. */
+function importedSymbol(t, node) {
+  const call = node.parent;
+  if (!call || !t.isCallExpression(call)) return false;
+  const next = call.arguments[call.arguments.indexOf(node) + 1];
+  return Boolean(next && isText(t, next) && PACKAGE_SPECIFIER.test(next.text));
+}
+
+const caseLabel = (t, node) => Boolean(node.parent && t.isCaseClause(node.parent) && node.parent.expression === node);
+
+const discriminator = (t, node) => Boolean(node.parent && t.isPropertyAssignment(node.parent) && node.parent.initializer === node
+  && t.isIdentifier(node.parent.name) && node.parent.name.text === 'type');
+
+/** The [pos, end) ranges of every comment of `source`. */
+function commentRanges(t, source) {
+  const text = source.text, ranges = [];
+  const visit = (node) => {
+    for (const range of t.getLeadingCommentRanges(text, node.getFullStart()) ?? []) ranges.push([range.pos, range.end]);
+    for (const range of t.getTrailingCommentRanges(text, node.end) ?? []) ranges.push([range.pos, range.end]);
+    t.forEachChild(node, visit);
+  };
+  visit(source);
+  return ranges;
+}
+
+/**
+ * The offsets to leave out of UPPER literal discovery for a parsed script: the opening quote of every read literal, and the start
+ * of every `patterns` match (RegExp with the g flag) that lies inside a comment.
+ */
+export function nonEmittingOffsets(t, source, patterns = []) {
+  const offsets = new Set();
+  const members = new Set();
+  const collect = (node) => {
+    if (t.isBinaryExpression(node) && node.operatorToken.kind === t.SyntaxKind.EqualsToken && t.isPropertyAccessExpression(node.left)
+      && isText(t, node.right) && node.right.text === node.left.name.text) members.add(node.right.text);
+    t.forEachChild(node, collect);
+  };
+  collect(source);
+  const visit = (node) => {
+    if (isText(t, node) && (members.has(node.text) || comparedValue(t, source, node) || queryArgument(t, node) || membershipElement(t, node) || caseLabel(t, node) || importedSymbol(t, node) || discriminator(t, node))) {
+      offsets.add(node.getStart(source));
+    }
+    t.forEachChild(node, visit);
+  };
+  visit(source);
+  const ranges = commentRanges(t, source);
+  if (ranges.length) {
+    for (const pattern of patterns) {
+      for (const match of source.text.matchAll(pattern)) {
+        if (ranges.some(([pos, end]) => match.index >= pos && match.index < end)) offsets.add(match.index);
+      }
+    }
+  }
+  return offsets;
+}

package/runtime/scripts/lib/gate-loosening.mjs

@@ -9,6 +9,9 @@
 //   spec-deleted       a spec file deleted in a change that also changes product code
 //   assertion-weakened a spec that loses more assertions than it gains in a change that also changes product code
 //   spec-skipped       a skip marker added to a spec in a change that also changes product code
+//   bypass-added, check-weakened, scope-widened (and check-removed over code): the code of a check is a gate too. A check script, rule module,
+//                      canon template, lint package, workflow or hook (modules/kernel/gate-loosening.yaml checkCode) that gains a bypass marker,
+//                      loses enforcement lines or ban-list rows, or gains an exemption is judged by scripts/lib/check-code-loosening.mjs
 // A change that renames paths (a git rename, `git diff -M`) may MOVE the entries that name them: a removed line and an added line of the
 // same file that are equal once every renamed prefix of the removed line is rewritten to its new name are one entry moved, not a check
 // removed and an exception added (renamedPrefixesOf, movedLinesOf). A moved entry that also changes in any other way (a widened glob, an
@@ -18,21 +21,53 @@
 // Only what a release shipped can be loosened (loosensReleased): a check, a spec or an assertion added after the release and folded
 // away before the next one never was a gate of a release.
 import { byCodeUnit } from './list.mjs';
+import { checkCodeFindings, isCheckCode } from './check-code-loosening.mjs';
 
 const LIST_ITEM = /^\s*-\s+\S/;
 const NUMBER_LINE = /^\s*(?:-\s+)?([A-Za-z][\w.-]*):\s*(-?\d+(?:\.\d+)?)\s*(?:#.*)?$/;
+/** A line of a JSON or JavaScript config as the YAML number line above reads it: no quotes around the key, no trailing comma or line comment. */
+function plainNumberLine(line) {
+  const comment = line.indexOf('//');
+  const code = (comment < 0 ? line : line.slice(0, comment)).trimEnd();
+  return (code.endsWith(',') ? code.slice(0, -1) : code).replace(/^(\s*(?:-\s+)?)["']([^"']+)["']:/, '$1$2:');
+}
+
+const concatenates = (line) => typeof line === 'string' && line.trimEnd().endsWith('+');
+
+/** Records one changed line of `current`; returns the removed text (the next line's `above`), or null. */
+function recordLine(current, line, section, above) {
+  if (line.startsWith('deleted file mode')) { current.deleted = true; return null; }
+  if (line.startsWith('+') && !line.startsWith('+++')) {
+    const text = line.slice(1);
+    current.added.push(text);
+    current.under.set(text, [...(current.under.get(text) ?? []), section]);
+    return null;
+  }
+  if (!line.startsWith('-') || line.startsWith('---')) return null;
+  const text = line.slice(1);
+  current.removed.push(text);
+  if (concatenates(above) || concatenates(text)) current.operands.add(text);
+  return text;
+}
 
-/** The files of a unified diff: [{file, deleted, added[], removed[]}] (changed lines without their marker). */
+/**
+ * The files of a unified diff: [{file, deleted, added[], removed[], under}] (changed lines without their marker). `under` maps an added line to the
+ * hunk headers it was added under (git prints the nearest line above the hunk that starts a word, so the key a YAML list item sits in).
+ * `operands` holds the removed lines that are an operand of a string concatenation: a line that ends in `+`, or one whose removed line just
+ * above it in the same hunk ends in `+` (a message being printed, never a row of a ban list).
+ */
 export function parseDiff(text) {
   const files = [];
   let current = null;
+  let section = '';
+  let above = null;
   for (const line of String(text ?? '').split(/\r?\n/)) {
     const header = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
-    if (header) { current = { file: header[2], deleted: false, added: [], removed: [] }; files.push(current); continue; }
+    if (header) { current = { file: header[2], deleted: false, added: [], removed: [], operands: new Set(), under: new Map() }; files.push(current); above = null; continue; }
     if (!current) continue;
-    if (line.startsWith('deleted file mode')) current.deleted = true;
-    else if (line.startsWith('+') && !line.startsWith('+++')) current.added.push(line.slice(1));
-    else if (line.startsWith('-') && !line.startsWith('---')) current.removed.push(line.slice(1));
+    const hunk = /^@@ .*? @@ ?(.*)$/.exec(line);
+    if (hunk) { section = hunk[1]; above = null; continue; }
+    above = recordLine(current, line, section, above);
   }
   return files;
 }
@@ -163,7 +198,7 @@ function checksRemoved(entry) {
   });
 }
 
-const numbersOf = (lines) => lines.map((line) => NUMBER_LINE.exec(line)).filter(Boolean).map((match) => ({ key: match[1], value: Number(match[2]) }));
+const numbersOf = (lines) => lines.map((line) => NUMBER_LINE.exec(plainNumberLine(line))).filter(Boolean).map((match) => ({ key: match[1], value: Number(match[2]) }));
 
 /** The thresholds of a gate file moved the loose way. */
 function thresholdsLowered(entry, rules) {
@@ -198,6 +233,12 @@ function specFindings(entry, files, rules) {
 
 const changesProduct = (files, rules) => files.some((entry) => !isSpec(entry.file, rules) && rules.productPrefixes.some((prefix) => entry.file.startsWith(prefix)));
 
+/** The findings of one file that is a gate file (its lists and numbers) or the code of a check (its numbers; its bypasses are checkCodeFindings'). */
+function gateFindings(entry, rules) {
+  if (rules.gateFiles.includes(entry.file)) return [...checksRemoved(entry), ...thresholdsLowered(entry, rules)];
+  return isCheckCode(entry.file, rules) ? thresholdsLowered(entry, rules) : [];
+}
+
 /**
  * Every loosening of the change `diffText`, sorted: [{id, kind, file, detail}]. `rules` is modules/kernel/gate-loosening.yaml; `renamed`
  * is the change's renamed prefixes (renamedPrefixesOf), whose moved entries are no loosening.
@@ -206,10 +247,10 @@ export function looseningsOf(diffText, rules, { renamed = [] } = {}) {
   const files = parseDiff(diffText).map((entry) => movedLinesOf(entry, renamed));
   const product = changesProduct(files, rules);
   const found = files.flatMap((entry) => [
-    ...(rules.gateFiles.includes(entry.file) ? [...checksRemoved(entry), ...thresholdsLowered(entry, rules)] : []),
+    ...gateFindings(entry, rules),
     ...(rules.allowlistFiles.includes(entry.file) ? entry.added.filter((value) => LIST_ITEM.test(value)).map((value) => ({ kind: 'allowlist-added', file: entry.file, detail: clip(trimmed(value)) })) : []),
     ...(product && isSpec(entry.file, rules) ? specFindings(entry, files, rules) : []),
-  ]);
+  ]).concat(checkCodeFindings(files, rules));
   return found.map((finding) => ({ ...finding, id: `${finding.kind}:${finding.file}:${finding.detail}` })).sort((a, b) => byCodeUnit(a.id, b.id));
 }
 
@@ -233,6 +274,7 @@ const shownDetail = (detail) => (detail.endsWith('…') ? detail.slice(0, -1) :
 /**
  * Whether `finding` loosens the state released at `base`, read through `read(rev, file)` (text, or null when the revision holds no such
  * file); `rules` gives the assertion markers. A finding stays only when
+ *   bypass-added        the added line is still in the file at HEAD (a bypass folded away before the next release never shipped)
  *   check-removed       the removed list item is an item of that gate file at the release commit
  *   spec-deleted        the spec exists at the release commit
  *   spec-skipped        the spec exists at the release commit
@@ -240,6 +282,8 @@ const shownDetail = (detail) => (detail.endsWith('…') ? detail.slice(0, -1) :
  * (every other kind loosens whenever its file existed at the release).
  */
 export function loosensReleased(finding, { base, read, rules }) {
+  // A bypass is judged by whether it still stands: one added and folded away before the next release never shipped.
+  if (finding.kind === 'bypass-added') return String(read('HEAD', finding.file) ?? '').split('\n').some((line) => line.trim() === finding.text);
   const before = read(base, finding.file);
   if (before === null) return false;
   if (finding.kind === 'check-removed') return before.split('\n').some((line) => line.trim().startsWith(shownDetail(finding.detail)));

package/runtime/scripts/lib/json-formats.mjs

@@ -0,0 +1,34 @@
+// json-formats.mjs - the JSON files whose format a tool requires, declared once by rule (a basename, a tool-fixed folder or a managed
+// fragment) and not file by file. A file of a listed format is not authored declarative source: npm, tsc, turbo, next-intl, Claude Code,
+// the stack tooling and Keycloak read it as JSON and nothing else, so no YAML or JS form of it exists. Everything else that is authored
+// config belongs in YAML, and the json-exceptions check (scripts/checks/check-json-exceptions.mjs) refuses it. Proven by the package spec
+// src/json-formats.spec.mjs over the bundled copy of this file.
+
+/** The base name of a slash path. */
+const baseOf = (rel) => rel.slice(rel.lastIndexOf('/') + 1);
+
+/**
+ * The declared formats: `id`, the `tool` that fixes the format and a `match(rel)` over a skill-relative slash path. A format names a
+ * kind of file (a base name or a folder the tool reads by position), never one path of this repository.
+ */
+export const JSON_FORMATS = Object.freeze([
+  { id: 'npm-manifest', tool: 'npm', match: (rel) => baseOf(rel) === 'package.json' || baseOf(rel) === 'package-lock.json' },
+  { id: 'typescript-config', tool: 'tsc', match: (rel) => /^tsconfig(\.[A-Za-z0-9-]+)*\.json$/.test(baseOf(rel)) },
+  { id: 'shared-tsconfig-preset', tool: 'tsc (extends)', match: (rel) => /^packages\/tsconfig\/[^/]+\.json$/.test(rel) },
+  { id: 'turbo-pipeline', tool: 'turbo', match: (rel) => baseOf(rel) === 'turbo.json' },
+  { id: 'nest-cli', tool: '@nestjs/cli', match: (rel) => baseOf(rel) === 'nest-cli.json' },
+  { id: 'tree-kind', tool: 'starci hfs (hfs.json at a tree root)', match: (rel) => baseOf(rel) === 'hfs.json' },
+  { id: 'claude-code-settings', tool: 'Claude Code', match: (rel) => /(^|\/)\.claude\/settings\.json$/.test(rel) },
+  { id: 'i18n-message-catalog', tool: 'next-intl', match: (rel) => /(^|\/)modules\/i18n\/messages\/[a-z]{2}(-[A-Za-z]+)?\.json$/.test(rel) },
+  { id: 'stack-environment', tool: 'starci stack (.starcistacks layout)', match: (rel) => /(^|\/)\.starcistacks\/[^/]+\/environment\.json$/.test(rel) },
+  { id: 'stack-infra-metadata', tool: 'starci stack (.starcistacks layout)', match: (rel) => /(^|\/)\.starcistacks\/[^/]+\/infra\/metadata\.json$/.test(rel) },
+  { id: 'keycloak-realm-import', tool: 'Keycloak realm import', match: (rel) => /(^|\/)\.starcistacks\/[^/]+\/infra\/compose\/realm-[^/]+\.json$/.test(rel) },
+  { id: 'package-scripts-fragment', tool: 'npm (scripts rendered into package.json)', match: (rel) => /^packages\/hfs\/templates\/app\/package-scripts[^/]*\/[^/]+\.json$/.test(rel) },
+  { id: 'async-event-contract', tool: 'starci app emit', match: (rel) => /(^|\/)be\/contracts\/[^/]+\/events(\.pin)?\.json$/.test(rel) },
+  { id: 'model-scorecard-snapshot', tool: 'scripts/agent/benchmark-snapshot.mjs', match: (rel) => /^benchmark\/snapshots\/[^/]+\.json$/.test(rel) },
+]);
+
+/** The declared format that fixes `rel`, or null: the file is authored JSON the check must refuse. */
+export function jsonFormatOf(rel) {
+  return JSON_FORMATS.find((format) => format.match(rel)) ?? null;
+}

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

@@ -14,7 +14,7 @@ export const packageAt = (dir, name) => {
 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) {
+function starciBin(dir) {
   const packageFile = packageAt(dir, '@starci/cli');
   if (packageFile) {
     try {

package/runtime/scripts/lib/properties.mjs

@@ -0,0 +1,16 @@
+// properties.mjs — the .properties file reader (key=value lines, # and ! comments).
+import fs from 'node:fs';
+
+/** `file` as {key: value}: blank lines and #/! comments skipped, the first = or : splits. Unreadable file → {}. */
+export function readProperties(file) {
+  const out = {};
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return out; }
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#') || line.startsWith('!')) continue;
+    const at = line.search(/[=:]/);
+    if (at > 0) out[line.slice(0, at).trim()] = line.slice(at + 1).trim();
+  }
+  return out;
+}

package/runtime/scripts/lib/provision-control-failure.mjs

@@ -0,0 +1,32 @@
+// provision-control-failure.mjs - why `starci provision <plan|show|accept>` could not read or accept a prepared operation, as one public code and one
+// value-free detail line. Pure: the caller (scripts/gates/provision-operation.mjs runProvisionControl) names the stage that failed and passes the error;
+// this never serializes an error message, which may quote a provider body or a value, only the error's own identifier.
+// The case that motivated it: an operation prepared by a lane runtime keeps its plan blob in THAT runtime's blob store, and the published CLI reading it
+// from another runtime found the ledger row but not the blob; a blanket `provision-control-unavailable` hid that.
+
+/** The stages of the control verb, in the order it runs them. */
+export const PROVISION_CONTROL_STAGES = Object.freeze(['ledger', 'plan', 'target', 'accept']);
+
+const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/u;
+const SHA = /^[a-f0-9]{64}$/u;
+
+/** The error's own code (ERR_SQLITE_ERROR, ENOENT) or class name, never its message; null when it has neither. */
+export function errorIdentifier(error) {
+  return [error?.code, error?.name].find((value) => typeof value === 'string' && IDENTIFIER.test(value)) ?? null;
+}
+
+/**
+ * {code, detail} for a failure of the control verb at `stage`. A plan blob the ledger names but this runtime's blob store does not hold is
+ * `provision-plan-blob-missing`; every other failure stays `provision-control-unavailable` with the stage and the error's identifier.
+ */
+export function provisionControlFailure(error, { stage, planSha = null, operationId = null } = {}) {
+  if (!PROVISION_CONTROL_STAGES.includes(stage)) throw new TypeError(`unknown provision control stage: ${String(stage)}`);
+  const id = errorIdentifier(error);
+  if (stage === 'plan' && id === 'ENOENT') {
+    const blob = typeof planSha === 'string' && SHA.test(planSha) ? `the plan blob ${planSha.slice(0, 12)}` : 'the plan blob';
+    const operation = typeof operationId === 'string' && IDENTIFIER.test(operationId) ? ` of operation ${operationId}` : '';
+    return { code: 'provision-plan-blob-missing', detail: `${blob}${operation} is not in this runtime's blob store: the operation was prepared by another runtime; run the control with the runtime that prepared it, or prepare the operation again with this one` };
+  }
+  const named = id ? ' (' + id + ')' : '';
+  return { code: 'provision-control-unavailable', detail: `the ${stage} stage failed${named}; the operation journal holds its state` };
+}

package/runtime/scripts/lib/sonar-new-code.mjs

@@ -0,0 +1,58 @@
+// sonar-new-code.mjs - the New Code definition a Sonar project is ensured with, and how each provider stores and reads it back. Pure.
+// Without a New Code definition a SonarQube Cloud project's gate status is NONE and the scanner's quality-gate wait reports the gate
+// "not set" (alpha.27: two example projects carried the gate but no New Code definition). The canonical
+// period is knowledge/sonar-gate.yaml `gate.newCodePeriod` of the repository's edition; a stack target may declare its own
+// `resource.newCodePeriod` of the same shape. SonarQube Server and Community Build store it through api/new_code_periods; SonarQube
+// Cloud has no such web service and keeps it as the project setting `sonar.leak.period` (a number of days, or `previous_version`).
+
+/** The period types a declaration may name, and whether each carries a value. */
+const NEW_CODE_TYPES = Object.freeze({ NUMBER_OF_DAYS: 'days', PREVIOUS_VERSION: 'none' });
+/** The setting SonarQube Cloud keeps a project's New Code definition in. */
+export const CLOUD_NEW_CODE_SETTING = 'sonar.leak.period';
+const MAX_DAYS = 90;
+
+/** A period of a closed shape: {type: NUMBER_OF_DAYS, value: 1..90} or {type: PREVIOUS_VERSION}; throws on anything else. */
+export function newCodePeriodOf(period) {
+  if (!period || typeof period !== 'object' || Array.isArray(period)) throw new Error('Invalid declared new code period');
+  const keys = Object.keys(period);
+  if (!keys.every((key) => key === 'type' || key === 'value') || !Object.hasOwn(NEW_CODE_TYPES, period.type)) throw new Error('Invalid declared new code period');
+  if (period.type === 'PREVIOUS_VERSION') {
+    if (period.value !== undefined) throw new Error('Invalid declared new code period');
+    return { type: 'PREVIOUS_VERSION' };
+  }
+  if (!Number.isInteger(period.value) || period.value < 1 || period.value > MAX_DAYS) throw new Error('Invalid declared new code period');
+  return { type: 'NUMBER_OF_DAYS', value: period.value };
+}
+
+/** The period a project target is ensured with: its own `resource.newCodePeriod` when declared, else the canonical one of the gate. */
+export function declaredNewCodePeriod(resource, canonical) {
+  return newCodePeriodOf(resource?.newCodePeriod ?? canonical);
+}
+
+/** The value SonarQube Cloud stores in `sonar.leak.period` for `period`. */
+export const cloudLeakValue = (period) => (period.type === 'PREVIOUS_VERSION' ? 'previous_version' : String(period.value));
+
+/**
+ * The write that sets `period` on `projectKey` for `provider`: {kind: 'setting', key, value} on SonarQube Cloud, else
+ * {kind: 'period', form: {project, type, value?}} for api/new_code_periods/set.
+ */
+export function newCodeWrite(provider, projectKey, period) {
+  if (provider === 'sonar-cloud') return { kind: 'setting', key: CLOUD_NEW_CODE_SETTING, value: cloudLeakValue(period) };
+  return { kind: 'period', form: { project: projectKey, type: period.type, ...(period.value === undefined ? {} : { value: String(period.value) }) } };
+}
+
+/**
+ * Whether a provider's readback holds `period`: on SonarQube Cloud the api/settings/values answer ({settings: [{key, value}]}),
+ * elsewhere the api/new_code_periods/show answer ({type, value}). A missing definition, another type or another value is no match.
+ */
+export function newCodeMatches(provider, readback, period) {
+  if (provider === 'sonar-cloud') {
+    const row = (readback?.settings ?? []).find((setting) => setting?.key === CLOUD_NEW_CODE_SETTING);
+    return row?.value === cloudLeakValue(period);
+  }
+  if (readback?.type !== period.type) return false;
+  return period.value === undefined || String(readback.value) === String(period.value);
+}
+
+/** The public proof of an ensured period: `NUMBER_OF_DAYS:30` or `PREVIOUS_VERSION`. */
+export const newCodeProof = (period) => (period.value === undefined ? period.type : `${period.type}:${period.value}`);

package/runtime/scripts/lib/starciwork-boundary.mjs

@@ -0,0 +1,164 @@
+// starciwork-boundary.mjs — the executable form of the .starciwork boundary (docs/ledger-db.md,
+// modules/schemas/work-layout.yaml shape.productPaths). A repository's .starciwork holds product content only:
+// the explicit path list below. Every other path is agent data (reports, checks, captures, draw rounds, UAT runs,
+// logs, caches, ledgers, worktrees), which lives in runtime.sqlite rows and content-addressed blobs outside
+// every repository. STARCIWORK_GITIGNORE is the .starciwork/.gitignore content of a product repository.
+//
+// Paths are relative to the .starciwork root, '/'-separated.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// The one source of the .starciwork/.gitignore text: the app root template `starci app sync` renders (packages/hfs/templates).
+const TEMPLATE = path.join(import.meta.dirname, '..', '..', 'packages', 'hfs', 'templates', 'app', 'starciwork.gitignore');
+const LITE_TEMPLATE = path.join(path.dirname(TEMPLATE), 'starciwork.gitignore-lite');
+
+// The record families that hold nothing but index.yaml and evidence.yaml (ui, impl, uat and ac have their own rows).
+const PLAIN_FAMILIES = Object.freeze(['br', 'fr', 'nfr', 'data', 'journey', 'decision', 'sds', 'contract', 'integration', 'gap', 'event']);
+const RECORD_FILE = /^(index|evidence)\.yaml$/;
+const UAT_FILE = /^(index\.yaml|evidence\.yaml|accounts\.yaml|fixtures\.yaml|seed\.sql|cleanup\.sql)$/;
+const PLAIN = new RegExp(`^(${PLAIN_FAMILIES.join('|')})$`);
+const ANY = /^.+$/;
+const REST = '**';
+// One or more record-name folders: a record may nest by name segment where a group needs it (br/title/required,
+// fr/cart/add, ui/<group>/<screen>, impl/<repo>/<group>/<name>). A nesting folder is never assets/ or an agent-data
+// folder (DENY_SEGMENT), so a capture or run can never pass as a record.
+const NEST = '+';
+const NEST_SEGMENT = /^(?!assets$).+$/;
+
+// Each pattern is a list of segment matchers: a string (exact), a RegExp (one segment), '+' (one or more record-name
+// folders) or '**' (one or more segments of anything). Order follows §5.1.
+const PRODUCT_PATTERNS = Object.freeze([
+  ['.gitignore'], ['.gitattributes'], ['workspace.yaml'], ['index.yaml'],
+  ['brand', RECORD_FILE], ['brand', 'assets', REST],
+  ['shell', RECORD_FILE],
+  ['_resources', /^(environments|identities|fixtures|runtimes)$/, ANY, REST],
+  ['_resources', 'grammar-captures', REST],
+  ['_derived', /^(index\.yaml|frontier\.md|critique\.yaml|critique\.md)$/],
+  ['features', 'index.yaml'],
+  ['features', ANY, 'index.yaml'],
+  ['features', ANY, /^(br|ac|fr|nfr|data|journey|decision|sds|ui|impl|uat|contract|integration|gap|event)$/, 'index.yaml'],
+  ['features', ANY, PLAIN, NEST, RECORD_FILE],
+  ['features', ANY, 'br', NEST, 'ac', NEST, RECORD_FILE],
+  ['features', ANY, 'ui', NEST, RECORD_FILE],
+  ['features', ANY, 'ui', NEST, /^(flow|lifecycle-interface)\.yaml$/],
+  ['features', ANY, 'ui', NEST, 'assets', REST],
+  ['features', ANY, 'impl', ANY, 'index.yaml'],
+  ['features', ANY, 'impl', ANY, NEST, RECORD_FILE],
+  ['features', ANY, 'uat', NEST, UAT_FILE],
+].map(Object.freeze));
+
+// Agent output that is refused even where a pattern above would admit it: draw rounds inside a ui record's
+// assets, stray report copies, evidence bundles, evidence/ captures and UAT runs anywhere, temp JSON.
+const DENY_SEGMENT = /^(draw-loop|evidence|runs|kernel-evidence|kernel-strays|kernel-approvals)$/;
+const DENY_FILE = /^(report.*\.json|.*\.tmp\.json)$/;
+
+const segs = (rel) => String(rel ?? '').replaceAll('\\', '/').split('/').filter((s) => s && s !== '.');
+const fits = (matcher, seg) => (typeof matcher === 'string' ? matcher === seg : matcher.test(seg));
+
+function denied(parts, { dir = false } = {}) {
+  // The last segment of a file path is a file name: `evidence.yaml` is a record file, never an evidence/ bundle.
+  const dirs = dir ? parts : parts.slice(0, -1);
+  if (dirs.some((s) => DENY_SEGMENT.test(s))) return true;
+  return !dir && parts.length > 0 && DENY_FILE.test(parts.at(-1));
+}
+
+// Match parts[i..] against pattern[p..]. `prefix`: parts is a directory, true when some file under it could match.
+function walk(pattern, p, parts, i, prefix) {
+  if (i === parts.length) return prefix ? p < pattern.length : p === pattern.length;
+  if (p === pattern.length) return false;
+  const m = pattern[p];
+  if (m === REST) return prefix || parts.length > i;
+  if (m === NEST) {
+    if (!NEST_SEGMENT.test(parts[i])) return false;
+    // consume this folder, then either stop nesting or keep nesting
+    return walk(pattern, p + 1, parts, i + 1, prefix) || walk(pattern, p, parts, i + 1, prefix);
+  }
+  return fits(m, parts[i]) && walk(pattern, p + 1, parts, i + 1, prefix);
+}
+const matchFile = (pattern, parts) => walk(pattern, 0, parts, 0, false);
+
+/** True when the FILE at `rel` (relative to .starciwork) is product content §5.1 admits. */
+export function isProductPath(rel) {
+  const parts = segs(rel);
+  if (!parts.length || denied(parts)) return false;
+  return PRODUCT_PATTERNS.some((p) => matchFile(p, parts));
+}
+
+/** The lite app boundary: its optional Work tree holds .gitignore, workspace.yaml and brand/** only. */
+export function isLiteProductPath(rel, { dir = false } = {}) {
+  const parts = segs(rel);
+  return (!dir && parts.length === 1 && ['.gitignore', 'workspace.yaml'].includes(parts[0]))
+    || (parts[0] === 'brand' && (parts.length > 1 || dir));
+}
+
+const ROOT_CACHE_DIRS = new Set(['settle-parity', 'settle-tail', 'runtime', 'canon-seams']);
+const ROOT_CACHE_FILE = /^(.*\.tmp\.json|tmp-.*\.json|scan-i18n.*\.json|runtime-budget\.json|ledger-anchor\.json|supervisor-precheck\.mjs)$/;
+
+/**
+ * The §5.2 category of a KNOWN agent-data path, or null when the path is not one. Known agent data — the
+ * categories scripts/work/validate/check-example-work.mjs refuses in a .starciwork tree [HFS_AGENT_DATA_TRACKED]:
+ * ledger, logs-db, worktrees, kernel-evidence, kernel-strays, evidence-bundle, capture (impl captures),
+ * layout-capture (shell/assets), uat-run, draw-round, interface-audit (features/<f>/operations/), stray-report,
+ * cache. A path that is neither known agent data nor on the §5.1 list
+ * (isProductPath) is drift: product records in a retired layout, kept and reported, never removed by a script.
+ */
+const rootAgentDataCategory = (parts, dir, top) => {
+  if (parts.length === 1 && !dir && top.startsWith('runtime.sqlite')) return 'ledger';
+  if (parts.length === 1 && !dir && top.startsWith('logs.sqlite')) return 'logs-db';
+  if (top === 'worktrees') return 'worktrees';
+  if (top === 'kernel-evidence') return 'kernel-evidence';
+  if (top === 'kernel-strays' || top === 'kernel-approvals') return 'kernel-strays';
+  if (ROOT_CACHE_DIRS.has(top) && (dir || parts.length > 1)) return 'cache';
+  if (parts.length === 1 && !dir && ROOT_CACHE_FILE.test(top)) return 'cache';
+  return null;
+};
+
+const nestedAgentDataCategory = (dirs, name) => {
+  if (dirs.includes('draw-loop')) return 'draw-round';
+  if (dirs.includes('runs') && dirs[0] === 'features' && dirs.includes('uat')) return 'uat-run';
+  if (dirs.includes('evidence')) return 'evidence-bundle';
+  if (dirs[0] === 'features' && dirs.includes('operations')) return 'interface-audit';
+  if (dirs[0] === 'features' && dirs.includes('impl') && dirs.includes('assets')) return 'capture';
+  if (dirs[0] === 'shell' && dirs[1] === 'assets') return 'layout-capture';
+  if (name && /^report.*\.json$/.test(name)) return 'stray-report';
+  if (name?.endsWith('.tmp.json')) return 'cache';
+  return null;
+};
+
+export function agentDataCategory(rel, { dir = false } = {}) {
+  const parts = segs(rel);
+  if (!parts.length) return null;
+  const top = parts[0];
+  const dirs = dir ? parts : parts.slice(0, -1);
+  const name = dir ? null : parts.at(-1);
+  return rootAgentDataCategory(parts, dir, top) ?? nestedAgentDataCategory(dirs, name);
+}
+
+/**
+ * The .starciwork/.gitignore of a product repository: deny everything at the root, re-admit
+ * the §5.1 roots, then deny agent output inside them. Tracked files are not affected by an ignore rule; a tracked
+ * agent file is removed by the change that drops it, not by this ignore.
+ *
+ * The template is read on first use, never at import: a caller that only needs the boundary predicates
+ * (cli.mjs reaches this module through check-example-work.mjs) must keep loading on a tree that carries no
+ * packages/hfs/templates copy; the read still fails loudly the moment the text itself is asked for.
+ */
+let cachedLines;
+const gitignoreLines = () => (cachedLines ??= Object.freeze(fs.readFileSync(TEMPLATE, 'utf8').trimEnd().split(/\r?\n/)));
+const frozenWrite = () => { throw new TypeError('STARCIWORK_GITIGNORE is a frozen view of the hfs template'); };
+export const STARCIWORK_GITIGNORE = new Proxy([], {
+  get: (_t, p) => Reflect.get(gitignoreLines(), p),
+  has: (_t, p) => Reflect.has(gitignoreLines(), p),
+  ownKeys: () => Reflect.ownKeys(gitignoreLines()),
+  getOwnPropertyDescriptor: (_t, p) => {
+    const d = Reflect.getOwnPropertyDescriptor(gitignoreLines(), p);
+    // The proxy target holds none of these slots: every index must report configurable, and 'length' must keep
+    // the writable shape of its non-configurable target slot.
+    if (!d) return d;
+    return p === 'length' ? { ...d, writable: true } : { ...d, configurable: true };
+  },
+  set: frozenWrite,
+  deleteProperty: frozenWrite,
+  defineProperty: frozenWrite,
+  setPrototypeOf: frozenWrite,
+});

package/runtime/scripts/lib/work-edition.mjs

@@ -0,0 +1,40 @@
+// The edition boundary for Work readers: lite keeps workspace identity, brand records and their authored assets.
+import fs from 'node:fs';
+import path from 'node:path';
+import { isLiteProductPath } from './starciwork-boundary.mjs';
+import { foldCase } from './path-key.mjs';
+import { WORK_DIR_NAME } from './roots.mjs';
+
+const appTemplatesRoot = path.resolve(import.meta.dirname, '..', '..', 'packages', 'hfs', 'templates', 'app');
+
+/** Unrendered Work seeds in this runtime's app skeletons are templates, not product records. */
+export function isWorkTemplatePath(file) {
+  const [skeleton, work] = foldCase(path.relative(appTemplatesRoot, path.resolve(file))).replaceAll('\\', '/').split('/');
+  return (skeleton === 'skeleton' || skeleton === 'skeleton-lite') && work === WORK_DIR_NAME;
+}
+
+/** Whether the app owning this Work root declares lite. Missing declarations retain the full reader contract. */
+export function isLiteWorkRoot(workRoot) {
+  if (!workRoot) return false;
+  try {
+    const declaration = JSON.parse(fs.readFileSync(path.join(path.dirname(path.resolve(workRoot)), 'hfs.json'), 'utf8'));
+    return declaration?.kind === 'app' && declaration?.edition === 'lite';
+  } catch { return false; }
+}
+
+/** Whether a reader may open `file`: external files are unaffected; lite Work paths keep workspace.yaml and brand/**. */
+export function workPathAllowed(workRoot, file, { dir = false } = {}) {
+  if (!isLiteWorkRoot(workRoot)) return true;
+  const rel = path.relative(path.resolve(workRoot), path.resolve(file)).replaceAll('\\', '/');
+  if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) return true;
+  return !rel || isLiteProductPath(rel, { dir });
+}
+
+/** Every forbidden entry directly below a lite Work root, including empty directories. Never read their contents. */
+export function liteWorkForbiddenPaths(workRoot) {
+  if (!isLiteWorkRoot(workRoot)) return [];
+  let entries;
+  try { entries = fs.readdirSync(workRoot, { withFileTypes: true }); } catch { return []; }
+  return entries.filter(entry => !isLiteProductPath(entry.name, { dir: entry.isDirectory() }))
+    .map(entry => path.join(workRoot, entry.name));
+}

package/scaffold/app.mjs

@@ -21,6 +21,7 @@ import { dbTypesPath, generateDbTypes } from '../emit/db-types.mjs';
 import { TEMPLATES_DIR, appSource, imageFiles, render, renderTargets, writeTargets } from '../sync/index.mjs';
 import { ScaffoldError } from './service.mjs';
 import { SUPABASE_PORT_VARIABLES, supabasePortVars } from './supabase-ports.mjs';
+import { testWorldFiles } from './test-world.mjs';
 import { FE_APP_SCRIPTS, PACKAGE_MANAGER, WORKSPACES, WORKSPACE_LINT, feAppPackageName } from '../runtime/scripts/hfs/rules/monorepo.mjs';
 import { isLinkLike } from '../runtime/scripts/api/fs/is-link-like.mjs';
 import { unlinkOnly } from '../runtime/scripts/api/fs/lib.mjs';
@@ -685,6 +686,8 @@ export function scaffoldApp({ name, into, presets, edition = 'full', authCallbac
       { path: `fe/packages/${name}-${pkg}/tsconfig.build.json`, content: jsonText(fePackageBuildTsconfig()) },
     ])),
     ...['app', 'be', 'fe'].flatMap(scope => skeletonOf(scope, app, { sonarGate: sonarGateName(parseYaml(fs.readFileSync(SONAR_GATE_FILE, 'utf8')), app.edition), timestamp, registryVisibility, ...supabasePortVars(name) })),
+    // A full app has a test world (integration, e2e and contract are rows of its release gate); lite has none (ruling:R212/case-3, hosting amended by owner:lite-production-swarm).
+    ...(app.edition === 'lite' ? [] : testWorldFiles(app)),
   ];
   const writes = scaffoldWrites(root, original);
   try {

package/scaffold/service.mjs

@@ -38,7 +38,7 @@ const words = name => name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z
 export const pascalOf = name => words(name).map(word => word[0].toUpperCase() + word.slice(1).toLowerCase()).join('');
 /** `InjectPrimaryEntityManager` -> `PRIMARY_ENTITY_MANAGER`. */
 const tokenNameOf = decorator => words(decorator.replace(/^Inject/, '')).map(word => word.toUpperCase()).join('_');
-const camelOf = name => { const pascal = pascalOf(name); return pascal[0].toLowerCase() + pascal.slice(1); };
+export const camelOf = name => { const pascal = pascalOf(name); return pascal[0].toLowerCase() + pascal.slice(1); };
 
 const SERVICE_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;