@quonfig/cli 0.0.66 → 0.0.68

package/dist/migrate/key-rewriter.d.ts

@@ -8,27 +8,57 @@ export interface KeyRewrite {
 }
 export declare function resetKeyRewriter(): void;
 /**
- * Pre-pass: compute the final key for every source key. Sorted first so the
- * assignment of the un-suffixed base name on a collision is deterministic and
- * independent of the order changes were fetched in.
+ * Seed the rewriter with the complete source->final map persisted by previous
+ * runs. Every persisted final is immediately marked taken (case-insensitively)
+ * so keys planned later this run can never claim one. Call after
+ * `resetKeyRewriter()` and before `planKeyRewrites()` — `planKeyRewritesForChanges`
+ * does this ordering for you.
+ */
+export declare function seedPersistedKeyPlan(keys: Readonly<Record<string, string>>): void;
+/**
+ * Pre-pass: compute the final key for every source key. Three passes, each
+ * sorted so every assignment is deterministic and independent of the order
+ * changes were fetched in:
+ *
+ *   0. Keys mapped by a PREVIOUS run keep their persisted final verbatim (see
+ *      `seedPersistedKeyPlan`) — full and delta runs must resolve identically.
+ *   1. Keys that are ALREADY fully valid (sanitize is an identity: they pass
+ *      Policy A and the FS-floor) claim their own names FIRST and are never
+ *      renamed to make room for sanitized junk — customer code calling
+ *      get("my-flag") must keep resolving to the same flag even when a source
+ *      key like "my flag" sanitizes to the same name. If two VALID keys
+ *      collide case-insensitively ("Foo"/"foo" — a genuine source conflict the
+ *      FS-floor hard-rejects), the lexicographically-first one keeps its name
+ *      and the other is suffixed.
+ *   2. Keys that needed sanitizing then disambiguate AROUND the valid ones
+ *      (-2, -3, ...).
  */
 export declare function planKeyRewrites(sourceKeys: Iterable<string>): void;
 /**
- * The final key for `sourceKey`. Uses the planned map when present, else a pure
+ * The final key for `sourceKey`. Uses the planned map when present, then the
+ * PERSISTED map (a delta run's flag can reference a segment that was migrated
+ * in the full run but is absent from the delta's change set), else a pure
  * sanitize (no disambiguation, no mutation) as a safe fallback.
  */
 export declare function resolveKey(sourceKey: string): string;
 /** Every key that was actually rewritten (conforming keys are omitted). */
 export declare function getKeyRewrites(): KeyRewrite[];
 /**
- * Run-level pre-pass: reset the rewriter and plan every source key BEFORE any
- * change is translated, so both key-definition and by-key reference sites
- * resolve against the same fully-disambiguated map. Structurally typed on
- * `{key?}` to stay decoupled from LegacyChange.
+ * The COMPLETE source->final map to persist to `.qf/key-plan.json`: every key
+ * planned this run (unchanged ones included) merged over everything persisted
+ * by previous runs, sorted by source key for stable on-disk diffs.
+ */
+export declare function getFullKeyPlan(): Record<string, string>;
+/**
+ * Run-level pre-pass: reset the rewriter, seed the persisted plan from any
+ * previous run, and plan every source key BEFORE any change is translated, so
+ * both key-definition and by-key reference sites resolve against the same
+ * fully-disambiguated map. Structurally typed on `{key?}` to stay decoupled
+ * from LegacyChange.
  */
 export declare function planKeyRewritesForChanges(changes: ReadonlyArray<{
     key?: string;
-}>): void;
+}>, persistedKeys?: Readonly<Record<string, string>>): void;
 /**
  * `--strict-keys` escape hatch: refuse to migrate if any source key would need
  * rewriting, so a customer who requires byte-identical keys can clean up the
@@ -41,10 +71,12 @@ export declare class StrictKeysError extends Error {
 /**
  * Plan the rewrites for a run and, when `strict`, throw `StrictKeysError` if any
  * key would be rewritten. Call once at the top of each migrate orchestrator
- * before translating.
+ * before translating. `persistedKeys` (from `readKeyPlan`) makes previously
+ * mapped keys resolve exactly as they did on the run that mapped them.
  */
 export declare function preflightKeyRewrites(changes: ReadonlyArray<{
     key?: string;
 }>, opts?: {
+    persistedKeys?: Readonly<Record<string, string>>;
     strict?: boolean;
 }): void;

package/dist/migrate/key-rewriter.js

@@ -22,11 +22,25 @@
  * unit calls to a source's path builders stay referentially transparent.
  */
 import { sanitizePolicyAKey } from './key-sanitize.js';
-const state = { bySource: new Map(), takenLower: new Map() };
+const state = { bySource: new Map(), persisted: new Map(), takenLower: new Map() };
 export function resetKeyRewriter() {
     state.bySource = new Map();
+    state.persisted = new Map();
     state.takenLower = new Map();
 }
+/**
+ * Seed the rewriter with the complete source->final map persisted by previous
+ * runs. Every persisted final is immediately marked taken (case-insensitively)
+ * so keys planned later this run can never claim one. Call after
+ * `resetKeyRewriter()` and before `planKeyRewrites()` — `planKeyRewritesForChanges`
+ * does this ordering for you.
+ */
+export function seedPersistedKeyPlan(keys) {
+    for (const [sourceKey, final] of Object.entries(keys)) {
+        state.persisted.set(sourceKey, final);
+        state.takenLower.set(final.toLowerCase(), sourceKey);
+    }
+}
 /** Find the first case-insensitively-free variant of `base` (base, base-2, ...). */
 function disambiguate(base) {
     if (!state.takenLower.has(base.toLowerCase()))
@@ -39,44 +53,110 @@ function disambiguate(base) {
             return candidate;
     }
 }
+/** Disambiguate `base`, record the mapping, and mark the final taken. */
+function assignFinal(sourceKey, base, sanitizeReasons) {
+    const final = disambiguate(base);
+    const reasons = [...sanitizeReasons];
+    if (final !== base)
+        reasons.push('appended a numeric suffix to keep the key unique');
+    state.bySource.set(sourceKey, { final, reasons, source: sourceKey });
+    state.takenLower.set(final.toLowerCase(), sourceKey);
+}
 /**
- * Pre-pass: compute the final key for every source key. Sorted first so the
- * assignment of the un-suffixed base name on a collision is deterministic and
- * independent of the order changes were fetched in.
+ * Pre-pass: compute the final key for every source key. Three passes, each
+ * sorted so every assignment is deterministic and independent of the order
+ * changes were fetched in:
+ *
+ *   0. Keys mapped by a PREVIOUS run keep their persisted final verbatim (see
+ *      `seedPersistedKeyPlan`) — full and delta runs must resolve identically.
+ *   1. Keys that are ALREADY fully valid (sanitize is an identity: they pass
+ *      Policy A and the FS-floor) claim their own names FIRST and are never
+ *      renamed to make room for sanitized junk — customer code calling
+ *      get("my-flag") must keep resolving to the same flag even when a source
+ *      key like "my flag" sanitizes to the same name. If two VALID keys
+ *      collide case-insensitively ("Foo"/"foo" — a genuine source conflict the
+ *      FS-floor hard-rejects), the lexicographically-first one keeps its name
+ *      and the other is suffixed.
+ *   2. Keys that needed sanitizing then disambiguate AROUND the valid ones
+ *      (-2, -3, ...).
  */
 export function planKeyRewrites(sourceKeys) {
-    for (const sourceKey of [...new Set(sourceKeys)].sort()) {
-        if (state.bySource.has(sourceKey))
+    const fresh = [...new Set(sourceKeys)].sort().filter((k) => !state.bySource.has(k));
+    // Pass 0: previously-mapped keys resolve to their persisted final, always.
+    const unpersisted = [];
+    for (const sourceKey of fresh) {
+        const persistedFinal = state.persisted.get(sourceKey);
+        if (persistedFinal === undefined) {
+            unpersisted.push(sourceKey);
             continue;
-        const san = sanitizePolicyAKey(sourceKey);
-        const final = disambiguate(san.key);
-        const reasons = [...san.reasons];
-        if (final !== san.key)
-            reasons.push('appended a numeric suffix to keep the key unique');
-        state.bySource.set(sourceKey, { final, reasons, source: sourceKey });
-        state.takenLower.set(final.toLowerCase(), sourceKey);
+        }
+        const sanitized = sanitizePolicyAKey(sourceKey);
+        const reasons = persistedFinal === sanitized.key
+            ? [...sanitized.reasons]
+            : [...sanitized.reasons, 'kept the key assigned by a previous import run'];
+        state.bySource.set(sourceKey, { final: persistedFinal, reasons, source: sourceKey });
+        state.takenLower.set(persistedFinal.toLowerCase(), sourceKey);
+    }
+    // Pass 1: already-valid keys claim their own names.
+    const needsSanitizing = [];
+    for (const sourceKey of unpersisted) {
+        const sanitized = sanitizePolicyAKey(sourceKey);
+        if (sanitized.changed) {
+            needsSanitizing.push({ sanitized, sourceKey });
+        }
+        else {
+            assignFinal(sourceKey, sourceKey, []);
+        }
+    }
+    // Pass 2: sanitized keys disambiguate around them.
+    for (const { sanitized, sourceKey } of needsSanitizing) {
+        assignFinal(sourceKey, sanitized.key, sanitized.reasons);
     }
 }
 /**
- * The final key for `sourceKey`. Uses the planned map when present, else a pure
+ * The final key for `sourceKey`. Uses the planned map when present, then the
+ * PERSISTED map (a delta run's flag can reference a segment that was migrated
+ * in the full run but is absent from the delta's change set), else a pure
  * sanitize (no disambiguation, no mutation) as a safe fallback.
  */
 export function resolveKey(sourceKey) {
     const planned = state.bySource.get(sourceKey);
-    return planned ? planned.final : sanitizePolicyAKey(sourceKey).key;
+    if (planned)
+        return planned.final;
+    const persisted = state.persisted.get(sourceKey);
+    if (persisted !== undefined)
+        return persisted;
+    return sanitizePolicyAKey(sourceKey).key;
 }
 /** Every key that was actually rewritten (conforming keys are omitted). */
 export function getKeyRewrites() {
     return [...state.bySource.values()].filter((r) => r.final !== r.source);
 }
 /**
- * Run-level pre-pass: reset the rewriter and plan every source key BEFORE any
- * change is translated, so both key-definition and by-key reference sites
- * resolve against the same fully-disambiguated map. Structurally typed on
- * `{key?}` to stay decoupled from LegacyChange.
+ * The COMPLETE source->final map to persist to `.qf/key-plan.json`: every key
+ * planned this run (unchanged ones included) merged over everything persisted
+ * by previous runs, sorted by source key for stable on-disk diffs.
+ */
+export function getFullKeyPlan() {
+    const merged = new Map(state.persisted);
+    for (const [source, rewrite] of state.bySource)
+        merged.set(source, rewrite.final);
+    const out = {};
+    for (const source of [...merged.keys()].sort())
+        out[source] = merged.get(source);
+    return out;
+}
+/**
+ * Run-level pre-pass: reset the rewriter, seed the persisted plan from any
+ * previous run, and plan every source key BEFORE any change is translated, so
+ * both key-definition and by-key reference sites resolve against the same
+ * fully-disambiguated map. Structurally typed on `{key?}` to stay decoupled
+ * from LegacyChange.
  */
-export function planKeyRewritesForChanges(changes) {
+export function planKeyRewritesForChanges(changes, persistedKeys) {
     resetKeyRewriter();
+    if (persistedKeys)
+        seedPersistedKeyPlan(persistedKeys);
     planKeyRewrites(changes.flatMap((c) => (typeof c.key === 'string' ? [c.key] : [])));
 }
 /**
@@ -97,10 +177,11 @@ export class StrictKeysError extends Error {
 /**
  * Plan the rewrites for a run and, when `strict`, throw `StrictKeysError` if any
  * key would be rewritten. Call once at the top of each migrate orchestrator
- * before translating.
+ * before translating. `persistedKeys` (from `readKeyPlan`) makes previously
+ * mapped keys resolve exactly as they did on the run that mapped them.
  */
 export function preflightKeyRewrites(changes, opts) {
-    planKeyRewritesForChanges(changes);
+    planKeyRewritesForChanges(changes, opts?.persistedKeys);
     if (opts?.strict) {
         const rewrites = getKeyRewrites();
         if (rewrites.length > 0)

package/dist/migrate/key-sanitize.js

@@ -35,6 +35,14 @@ function shortHash(raw) {
 export function sanitizePolicyAKey(raw) {
     const reasons = [];
     let k = raw;
+    // 0. Trim leading/trailing whitespace FIRST, so an edge space is dropped (a
+    //    trailing space is an FS-floor violation — stripped by Windows) rather
+    //    than surviving as a cosmetic dash via the charset replacement below.
+    const wsTrimmed = k.replaceAll(/^\s+|\s+$/g, '');
+    if (wsTrimmed !== k) {
+        k = wsTrimmed;
+        reasons.push('trimmed leading/trailing whitespace');
+    }
     // 1. Path separators -> dot. Preserves the dotted-hierarchy intent (a `/` or
     //    `\` in a source key becomes a namespace dot, matching the historical
     //    normalizeKey) rather than a lossy dash.
@@ -47,13 +55,16 @@ export function sanitizePolicyAKey(raw) {
         k = k.replaceAll(/[^A-Za-z0-9._-]+/g, '-');
         reasons.push('replaced disallowed characters with "-"');
     }
-    // 3. Trim leading/trailing separators. A leading dot is silently skipped by
-    //    the loader/verify; a trailing dot or space is stripped by Windows. A
-    //    leading/trailing dash is merely cosmetic but trimmed for tidiness.
-    const trimmed = k.replaceAll(/^[.-]+/g, '').replaceAll(/[.-]+$/g, '');
+    // 3. Trim leading/trailing DOTS only. A leading dot is silently skipped by
+    //    the loader/verify; a trailing dot is stripped by Windows — both are
+    //    floor violations. Leading/trailing DASHES are fully legal under Policy A
+    //    and the floor, so they are deliberately NOT trimmed: this function must
+    //    be an identity on every already-valid key (otherwise --strict-keys
+    //    aborts on keys the platform accepts, and a valid key gets "rewritten").
+    const trimmed = k.replaceAll(/^\.+/g, '').replaceAll(/\.+$/g, '');
     if (trimmed !== k) {
         k = trimmed;
-        reasons.push('trimmed leading/trailing separators');
+        reasons.push('trimmed leading/trailing dots');
     }
     // 4. Windows reserved device name on the FIRST dot-segment (the segment the
     //    floor checks) -> suffix "_" so `con` -> `con_`, `nul.foo` -> `nul_.foo`.
@@ -68,11 +79,20 @@ export function sanitizePolicyAKey(raw) {
         k = 'new-key';
         reasons.push('escaped reserved key "new"');
     }
-    // 6. Empty after sanitizing (e.g. the source key was all disallowed chars).
+    // 6. Empty — or reduced to pure separator junk — after sanitizing (e.g. the
+    //    source key was all disallowed chars, so every char became a dash). The
+    //    `k !== raw` guard keeps this an identity on ALREADY-valid separator-only
+    //    keys like "-" (legal under Policy A); only keys we transformed into
+    //    meaningless separators get the stable placeholder, so distinct junk
+    //    source keys ("!!!" vs "???") stay distinguishable.
     if (k.length === 0) {
         k = `key-${shortHash(raw)}`;
         reasons.push('key was empty after sanitizing');
     }
+    else if (k !== raw && !/[A-Za-z0-9_]/.test(k)) {
+        k = `key-${shortHash(raw)}`;
+        reasons.push('key had no letters, numbers, or underscores after sanitizing');
+    }
     // 7. Length cap 200 (ASCII-only == byte length). Stable hash suffix keeps two
     //    long keys sharing a 200-char prefix from colliding.
     if (k.length > MAX_KEY_LEN) {

package/dist/migrate/local-write.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { removeQfFromGitignore, writeImportState } from './import-state.js';
-import { getKeyRewrites, preflightKeyRewrites } from './key-rewriter.js';
+import { readKeyPlan, removeQfFromGitignore, writeImportState, writeKeyPlan } from './import-state.js';
+import { getFullKeyPlan, getKeyRewrites, preflightKeyRewrites } from './key-rewriter.js';
 import { deriveFollowUpFromConversionNotes, writeMigrationReport } from './migration-report.js';
 import { detectDuplicateKeys } from './sources/launch/translate.js';
 import { MIGRATOR_IDENTITY, stackCommits } from '../util/clone-and-stack-push.js';
@@ -184,8 +184,13 @@ export const applyLocalMigration = async (opts) => {
     const author = opts.author ?? MIGRATOR_IDENTITY;
     // qfg-6na9.3: plan Policy A key rewrites over ALL changes up front (run-level,
     // not per-commit) so key-def and reference sites resolve identically, then
-    // enforce --strict-keys before writing anything.
-    preflightKeyRewrites(opts.changes, { strict: opts.strictKeys });
+    // enforce --strict-keys before writing anything. Mappings persisted by a
+    // previous run (.qf/key-plan.json) are authoritative so a delta run cannot
+    // replan a subset and land on different finals.
+    preflightKeyRewrites(opts.changes, {
+        persistedKeys: readKeyPlan(opts.localDir) ?? undefined,
+        strict: opts.strictKeys,
+    });
     if (opts.fullHistory && !opts.source.getCommitMeta) {
         throw new Error(`--full-summary requires the source to provide per-change author + date + summary, but \`${opts.source.name}\` does not. ` +
             `Drop --full-summary or use a source (e.g. launch) that supports it.`);
@@ -200,6 +205,7 @@ export const applyLocalMigration = async (opts) => {
     const { livePaths, resolutions: resolutionEntries } = writeQuonfigFiles(opts.localDir, opts.changes, opts.source);
     removeQfFromGitignore(opts.localDir);
     writeImportState(opts.localDir, opts.importState);
+    writeKeyPlan(opts.localDir, getFullKeyPlan());
     const droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
     const skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
     const coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
@@ -347,6 +353,7 @@ export const buildAuditFinalCommit = (opts) => ({
         const duplicateResolutions = resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
         removeQfFromGitignore(dir);
         writeImportState(dir, opts.importState);
+        writeKeyPlan(dir, getFullKeyPlan());
         const skippedTotal = (skippedConfigs?.total ?? 0) + resolutionEntries.reduce((sum, r) => sum + r.deleted.length, 0);
         const counts = buildMigrationCounts(livePaths, opts.environments.length, skippedTotal);
         const reportData = {

package/dist/migrate/migration-report.js

@@ -613,5 +613,11 @@ export const writeMigrationReport = (outputDir, data) => {
             source: data.source,
         }, null, 2) + '\n', 'utf8');
     }
+    else {
+        // key-map.json describes ONE run's rewrites. A later run with zero
+        // rewrites must not leave a stale map from a previous run lying around
+        // implying those keys were rewritten by this run.
+        fs.rmSync(keyMapPath(outputDir), { force: true });
+    }
     return filePath;
 };

package/dist/migrate/push-to-cloud.js

@@ -1,8 +1,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { removeQfFromGitignore, writeImportState } from './import-state.js';
+import { readKeyPlan, removeQfFromGitignore, writeImportState, writeKeyPlan } from './import-state.js';
 import { buildAuditFinalCommit, buildAuditPerChangeCommits, buildMigrationCommitMessage, buildMigrationCounts, writeQuonfigFiles, } from './local-write.js';
-import { getKeyRewrites, preflightKeyRewrites } from './key-rewriter.js';
+import { getFullKeyPlan, getKeyRewrites, preflightKeyRewrites } from './key-rewriter.js';
 import { deriveFollowUpFromConversionNotes, writeMigrationReport } from './migration-report.js';
 import { cloneAndStackPush, } from '../util/clone-and-stack-push.js';
 import { formatResult, validateWorkspace } from '../verify/validate.js';
@@ -58,8 +58,15 @@ export const pushMigrationToCloud = async (opts) => {
     }
     // qfg-6na9.3: plan Policy A key rewrites over ALL changes up front (run-level,
     // not per-commit) so key-def and reference sites resolve identically, then
-    // enforce --strict-keys before any clone/commit/push.
-    preflightKeyRewrites(opts.changes, { strict: opts.strictKeys });
+    // enforce --strict-keys before any clone/commit/push. Mappings persisted by a
+    // previous run (.qf/key-plan.json in the reused clone) are authoritative so a
+    // delta run cannot replan a subset and land on different finals. (When the
+    // clone is fresh, the plan only comes down WITH the clone — the collapsed
+    // commit's apply() re-plans below once it can read the cloned .qf/.)
+    preflightKeyRewrites(opts.changes, {
+        persistedKeys: readKeyPlan(opts.localDir) ?? undefined,
+        strict: opts.strictKeys,
+    });
     const acc = {
         coercedSentinels: null,
         droppedOverrides: null,
@@ -90,10 +97,19 @@ export const pushMigrationToCloud = async (opts) => {
             {
                 message: () => computedCommitMessage,
                 async apply(dir) {
+                    // Re-plan now that the clone exists: a FRESH clone of a previously
+                    // migrated workspace delivers .qf/key-plan.json only at this point
+                    // (the pre-clone preflight above couldn't see it), and the
+                    // persisted mappings must win before any file is written.
+                    preflightKeyRewrites(opts.changes, {
+                        persistedKeys: readKeyPlan(dir) ?? undefined,
+                        strict: opts.strictKeys,
+                    });
                     mergeEnvsIfPresent(dir);
                     const { livePaths, resolutions: resolutionEntries } = writeQuonfigFiles(dir, opts.changes, opts.source);
                     removeQfFromGitignore(dir);
                     writeImportState(dir, opts.importState);
+                    writeKeyPlan(dir, getFullKeyPlan());
                     acc.droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
                     acc.skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
                     acc.coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;

package/dist/verify/standalone.d.ts

@@ -10,4 +10,16 @@
  *   0  All checks pass
  *   1  Validation errors found
  */
-export {};
+/**
+ * Read all JSON config files from a git commit using `git show`.
+ * Works in bare repos (no working tree needed).
+ *
+ * qfg-6na9.6: uses execFileSync (never a shell) and `ls-tree -z` (NUL-delimited,
+ * disables git's C-quoting of "unusual" paths). The old string-interpolated
+ * execSync + default ls-tree output silently SKIPPED any filename containing a
+ * space or non-ASCII char — exactly the Policy-A-violating keys the hook
+ * exists to catch (verified live on staging: a `configs/bad charset key.json`
+ * push was accepted unvalidated). A listed-but-unreadable file is now a hard
+ * failure (fail closed), not a silent skip.
+ */
+export declare function readFilesFromCommit(commitOid: string, cwd?: string): Map<string, string>;

package/dist/verify/standalone.js

@@ -10,7 +10,7 @@
  *   0  All checks pass
  *   1  Validation errors found
  */
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import * as readline from 'node:readline';
 import { formatResult, validateFileMap, validateWorkspace } from './validate.js';
 async function main() {
@@ -91,42 +91,50 @@ async function runGitHook() {
 /**
  * Read all JSON config files from a git commit using `git show`.
  * Works in bare repos (no working tree needed).
+ *
+ * qfg-6na9.6: uses execFileSync (never a shell) and `ls-tree -z` (NUL-delimited,
+ * disables git's C-quoting of "unusual" paths). The old string-interpolated
+ * execSync + default ls-tree output silently SKIPPED any filename containing a
+ * space or non-ASCII char — exactly the Policy-A-violating keys the hook
+ * exists to catch (verified live on staging: a `configs/bad charset key.json`
+ * push was accepted unvalidated). A listed-but-unreadable file is now a hard
+ * failure (fail closed), not a silent skip.
  */
-function readFilesFromCommit(commitOid) {
+export function readFilesFromCommit(commitOid, cwd) {
     const files = new Map();
     const dirs = ['configs', 'feature-flags', 'segments', 'log-levels', 'schemas', 'schemas-protected'];
     for (const dir of dirs) {
-        // List files in this directory at the given commit
-        let listing;
-        try {
-            listing = execSync(`git ls-tree --name-only ${commitOid} ${dir}/`, {
-                encoding: 'utf8',
-                stdio: ['pipe', 'pipe', 'pipe'],
-            });
-        }
-        catch {
-            // Directory doesn't exist in this commit
-            continue;
-        }
-        const filenames = listing.trim().split('\n').filter(Boolean);
+        // List files in this directory at the given commit. A directory that
+        // doesn't exist yields an empty listing (exit 0); a bad/unreadable OID
+        // throws — fail closed, the hook rejects the push.
+        const listing = execFileSync('git', ['ls-tree', '-z', '--name-only', commitOid, `${dir}/`], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const filenames = listing.split('\0').filter(Boolean);
         for (const filePath of filenames) {
             if (!filePath.endsWith('.json') || filePath.includes('/.'))
                 continue;
-            try {
-                const content = execSync(`git show ${commitOid}:${filePath}`, {
-                    encoding: 'utf8',
-                    stdio: ['pipe', 'pipe', 'pipe'],
-                });
-                files.set(filePath, content);
-            }
-            catch {
-                // File can't be read, skip
-            }
+            // Fail closed: if a listed file can't be read, the push must not be
+            // accepted with that file unvalidated — let the error propagate to the
+            // hook's per-ref handler, which rejects the push.
+            const content = execFileSync('git', ['show', `${commitOid}:${filePath}`], {
+                cwd,
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            files.set(filePath, content);
         }
     }
     return files;
 }
-main().catch((error) => {
-    console.error(`qfg-verify: fatal: ${error.message}`);
-    process.exit(1);
-});
+// Only run as a program when compiled/executed as the entry point (Bun sets
+// import.meta.main; under node test imports it is undefined) — this lets tests
+// import readFilesFromCommit without triggering the CLI.
+if (import.meta.main) {
+    main().catch((error) => {
+        console.error(`qfg-verify: fatal: ${error.message}`);
+        process.exit(1);
+    });
+}

package/dist/verify/validate.js

@@ -808,8 +808,9 @@ function validateEnvironmentIds(environments, file, issues) {
 // IMPORTANT: this floor must stay conceptually in lockstep with app-quonfig's
 // src/lib/domain/config-schemas.ts (the charset precedent there is
 // `SchemaKeySchema`; Policy A is `PolicyAKeySchema`). The general charset check
-// (`^[A-Za-z0-9._-]+$`) is deliberately NOT here — it ships separately as a
-// warning (bead qfg-6na9.5). This module is the FS-floor + dedup only.
+// (`^[A-Za-z0-9._-]+$`) is deliberately NOT here — it lives in `validateKey`
+// below (warning per qfg-6na9.5, hard error since qfg-6na9.6). This list is the
+// FS-floor only.
 //
 // Structured as a table so severity is trivially adjustable later.
 const FS_SAFETY_FLOOR_CHECKS = [
@@ -848,20 +849,20 @@ export function validateKey(key, file, issues) {
             issues.push({ file, message: check.message, severity: 'error' });
         }
     }
-    // qfg-6na9.5: the general Policy A charset as a WARNING — the warn stage of the
-    // warn->error soak (project/plans/26-06-tighter-naming.md). A config that trips
-    // this must STILL push, so severity is 'warning' (does not set result.valid =
-    // false); qfg-6na9.6 will flip it to a hard error after a clean soak. The
-    // charset `^[A-Za-z0-9._-]+$` is kept in sync with app-quonfig's
-    // PolicyAKeySchema (hard at create). Skipped when this key already earned a
-    // hard error above (e.g. a Windows-reserved char is both a floor error AND a
-    // charset miss) so we don't double-report the same key.
+    // qfg-6na9.6: the general Policy A charset as a HARD ERROR. Shipped as a
+    // warning first (qfg-6na9.5), flipped after a full-corpus enumeration of all
+    // prod workspaces verified zero non-conforming keys (2026-07-03; see the bead
+    // and project/plans/26-06-tighter-naming.md). The charset `^[A-Za-z0-9._-]+$`
+    // is kept in sync with app-quonfig's PolicyAKeySchema (hard at create).
+    // Skipped when this key already earned an error above (e.g. a
+    // Windows-reserved char is both a floor error AND a charset miss) so we
+    // don't double-report the same key.
     // eslint-disable-next-line unicorn/better-regex -- keep the explicit charset in sync with app-quonfig
     if (issues.length === errorsBefore && !/^[A-Za-z0-9._-]+$/.test(key)) {
         issues.push({
             file,
-            message: `Key "${key}" has characters outside the allowed set (letters, numbers, ".", "-", "_"). This will become a hard error in a future release — rename it to conform.`,
-            severity: 'warning',
+            message: `Key "${key}" has characters outside the allowed set (letters, numbers, ".", "-", "_").`,
+            severity: 'error',
             suggestion: `Rename to use only letters, numbers, ".", "-", and "_"`,
         });
     }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "0.0.66";
+declare const _default: "0.0.68";
 export default _default;

package/dist/version.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED from package.json by scripts/generate-version.mjs — do not edit.
-export default '0.0.66';
+export default '0.0.68';