devflow-kit 3.6.0 → 3.8.0

package/dist/core/curation-queue-cleanup.js

@@ -0,0 +1,134 @@
+/**
+ * @file curation-queue-cleanup.ts
+ *
+ * The curation queue drains: `drainCurationQueue`, which `devflow curation --clear`
+ * runs (src/cli/commands/curation.ts), and `drainDisabledCurationQueue`, which `devflow
+ * curation --disable` and the drain `devflow init` runs when curation is switched off
+ * (src/cli/commands/init.ts) run: the same drain, and the pending rows of the backups
+ * a move left as well.
+ *
+ * Both drains answer `skipped`, and delete nothing, when git tracks any entry under a
+ * data folder or a backup folder, or does not answer (the tracked-areas check). The
+ * line a caller prints for such a drain is {@link formatCurationNotDrained}.
+ */
+import * as path from 'path';
+import { LEGACY_NAMES, getCurationClaimOwnerPath, getCurationDir, getCurationPendingTurnsPath, getCurationPendingTurnsProcessingPath, } from './project-paths.js';
+import { loadCurationMove } from './curation-move.js';
+import { MOVE_SKIP_NOTICE } from './curation-move-skip.js';
+import { formatCurationStoreUnavailable } from './curation-store.js';
+import { drainQueueFiles, formatRefusedDrain } from './queue-drain.js';
+import { loadTrackedAreas } from './tracked-areas.js';
+/** The folders to check for links, and the queue files to delete, in the live and the old ledger folder of `gitRoot`. */
+function liveQueueTargets(gitRoot) {
+    const curationDir = getCurationDir(gitRoot);
+    const devflowDir = path.dirname(curationDir);
+    const oldDir = path.join(devflowDir, LEGACY_NAMES.folder);
+    const queueFiles = [
+        getCurationPendingTurnsPath(gitRoot),
+        getCurationPendingTurnsProcessingPath(gitRoot),
+        getCurationClaimOwnerPath(gitRoot),
+    ];
+    return {
+        folders: [devflowDir, curationDir, oldDir],
+        files: [...queueFiles, ...queueFiles.map(file => path.join(oldDir, path.basename(file)))],
+    };
+}
+/**
+ * Drain the curation (decisions-detection) pending-turns queue, its claimed
+ * batch and the claim's owner file so stale turns don't process later — used by
+ * `--clear`. A mid-run Curate agent whose claimed batch vanishes aborts without
+ * changes, which is the desired outcome.
+ *
+ * Drains each ledger folder that exists, the new name and the old one: a move that
+ * was busy or refused leaves the old folder in place, and its queue must not process
+ * on a later re-enable. A folder or file that is absent is skipped. Only the three
+ * queue files go; the ledger, the log and the tuning file stay, and so does every
+ * backup folder a move left (see {@link drainDisabledCurationQueue}).
+ *
+ * Asks first the question the disable drain asks (see {@link drainDisabledCurationQueue}):
+ * when git tracks any entry under the data folders or a backup folder of `gitRoot`, or
+ * a `.git` entry stands and git does not answer, nothing is deleted and the answer is
+ * `skipped`.
+ *
+ * Refused, deleting nothing in either folder, when `.devflow` or either ledger
+ * folder under `gitRoot` is a symbolic link (D-CLI-NO-SYMLINK). ENOENT-tolerant;
+ * other errors propagate.
+ *
+ * `loadTracking` is the check's loader; its default is the package's own copy.
+ */
+export async function drainCurationQueue(gitRoot, loadTracking = loadTrackedAreas) {
+    const skipped = trackedSkip(gitRoot, loadTracking);
+    if (skipped !== null)
+        return skipped;
+    const { folders, files } = liveQueueTargets(gitRoot);
+    return drainQueueFiles(folders, files);
+}
+/**
+ * The drain of a switched-off curation: {@link drainCurationQueue}, and the pending
+ * rows of the backup folders a move left as well. A backup's queue, claim, private and
+ * overflow files go (the files `devflow curation --status` counts as pending rows);
+ * its ledger files, its swept files and the claim's owner file stay. Without this, a
+ * later re-enable and init would merge the backup's rows into the live queue, which is
+ * the turns the drain exists to discard. The backups are read within the sweep's
+ * bounds: 500 backup folders, and 200 files in each.
+ *
+ * Asks first whether git tracks any entry under the data folders or a backup folder of
+ * `gitRoot`, the question the move asks (the tracked-areas check). A folder that git
+ * tracks is the repository's content, so the drain leaves the project alone: it deletes
+ * nothing in the live folder, the old folder or any backup, and answers `skipped` with
+ * the reason `tracked`, or `unknown` when a `.git` entry stands and git did not answer
+ * (a check that cannot be loaded, or a root that is not absolute, answers `unknown`
+ * too). A root with no `.git` entry makes no git call and drains as usual.
+ *
+ * Refused, deleting nothing anywhere, when a link is in the way: `.devflow`, either
+ * ledger folder, a backup folder that may hold rows, or one of a backup's queue files.
+ * The answer names the link. ENOENT-tolerant. Any other failure of the backup list, a
+ * move module that does not load or a folder that cannot be read, never stops the
+ * drain of the live and the old folder: those drain as usual, and the answer carries
+ * a `warning` that the backups were not drained, which the caller prints.
+ *
+ * `load` is the move module's loader and `loadTracking` the check's; each default is
+ * the package's own copy.
+ */
+export async function drainDisabledCurationQueue(gitRoot, load = loadCurationMove, loadTracking = loadTrackedAreas) {
+    const skipped = trackedSkip(gitRoot, loadTracking);
+    if (skipped !== null)
+        return skipped;
+    const { folders, files } = liveQueueTargets(gitRoot);
+    const loaded = load();
+    const listed = loaded.ok ? loaded.value.backupQueueFiles(gitRoot) : null;
+    if (listed !== null && !listed.ok && listed.error.kind === 'refused' && listed.error.path !== undefined) {
+        return { drained: false, linkedFolder: listed.error.path };
+    }
+    const drain = await drainQueueFiles(folders, [...files, ...(listed !== null && listed.ok ? listed.value.files : [])]);
+    if (!drain.drained)
+        return drain;
+    const failure = !loaded.ok ? formatCurationStoreUnavailable(loaded.error) : listed !== null && !listed.ok ? listed.error.message : null;
+    return failure === null ? drain : { drained: true, warning: formatBackupsNotDrained(failure) };
+}
+/**
+ * The skipped answer for `root`, or null when the drain may go on. The tracked-areas
+ * check decides; a check that cannot be loaded cannot answer, so it is `unknown`.
+ */
+function trackedSkip(root, load) {
+    const loaded = load();
+    const answer = loaded.ok ? loaded.value.checkTrackedAreas(root) : 'unknown';
+    return answer === 'untracked' ? null : { drained: false, skipped: answer };
+}
+/**
+ * The line a caller prints for a drain that deleted nothing: the fixed notice of a
+ * skipped project (no repository content in it), or the refusal at a link. When the
+ * caller has just printed that notice (`shown`, the reason it showed), the line does
+ * not repeat it.
+ */
+export function formatCurationNotDrained(drain, shown = null) {
+    if (!('skipped' in drain))
+        return formatRefusedDrain('curation', drain.linkedFolder);
+    const line = 'The curation queue was not drained.';
+    return shown === drain.skipped ? line : `${line} ${MOVE_SKIP_NOTICE[drain.skipped]}`;
+}
+/** The warning for a disable drain that could not list the backups: the live queue is drained, the backups are not. */
+function formatBackupsNotDrained(reason) {
+    return `The queue files of the backup folders were not drained: ${reason}. The live curation queue was drained.`;
+}
+//# sourceMappingURL=curation-queue-cleanup.js.map

package/dist/core/curation-store.js

@@ -0,0 +1,98 @@
+/**
+ * The CLI's view of the curation store — a typed seam onto the package's own
+ * `hooks/lib/curation-store.cjs`, never a second implementation of it.
+ *
+ * D-LEARNING-STORE-SEAM: `devflow curation` reads and writes the curation tree only
+ * through the store module json-helper's ops and the hooks run, loaded with the
+ * evidence-policy seam's `loadScript` from the package's own scripts directory and
+ * shape-checked against CURATION_STORE_SURFACE; the interfaces below are
+ * TRANSCRIBED from the store's JSDoc and are this side's only shape authority.
+ * Reason: the CLI's own TypeScript reader judged every row by the v1 shape, so it
+ * counted v2 observations as invalid, and its `--clear` truncated the log without
+ * the lock every curation writer takes.
+ *
+ * As with the evidence resolver (D-POLICY-CJS-SEAM), the CLI loads the package
+ * copy, which `npm` installs with this CLI, not `~/.devflow/scripts`, which
+ * `devflow init` refreshes: the two can differ until the next init.
+ */
+import { join } from 'path';
+import { scriptsDir } from './assets.js';
+import { loadScript } from './evidence-policy.js';
+/** The store, relative to src/assets/scripts/ (and ~/.devflow/scripts/). */
+export const CURATION_STORE_SCRIPT_NAME = join('hooks', 'lib', 'curation-store.cjs');
+/**
+ * Every kind a store or move function can refuse with: the `kind` literals in
+ * curation-store.cjs and curation-move.cjs, the refusal builders' kinds, and the
+ * `successor-` kinds the retire op derives from the kind of its successor lookup.
+ * A test keeps this list equal to the kinds those modules name.
+ */
+export const CURATION_STORE_ERROR_KINDS = [
+    'no-curation-dir',
+    'not-a-directory',
+    'not-a-file',
+    'busy',
+    'refused',
+    'io-error',
+    'invalid-input',
+    'invalid-key',
+    'not-found',
+    'duplicate-anchor',
+    'ledger-malformed',
+    'heartbeat-failed',
+    'restore-first',
+    'duplicate-log-id',
+    'cannot-reproject',
+    'not-in-log',
+    'already-promoted',
+    'v1-observation',
+    'type-mismatch',
+    'cited-numbers-exhausted',
+    'no-verify-ref',
+    'not-at-ref',
+    'git-failed',
+    'quote-not-found',
+    'already-inactive',
+    'already-active',
+    'successor-not-found',
+    'successor-duplicate-anchor',
+    'successor-inactive',
+];
+/**
+ * Every key of CurationStoreModule and the runtime kind the loader requires of
+ * it. `satisfies` makes the compiler reject an interface key missing here.
+ */
+export const CURATION_STORE_SURFACE = Object.freeze({
+    INACTIVE_STATUSES: 'string-array',
+    ANCHOR_ID_RE: 'regexp',
+    readCurationState: 'function',
+    buildListing: 'function',
+    readListing: 'function',
+    formatListing: 'function',
+    showByKey: 'function',
+    restoreAnchor: 'function',
+    clearUnreferenced: 'function',
+    resetCuration: 'function',
+});
+/**
+ * Load the curation store from `dir` (default: the package's own scripts
+ * directory) and shape-check its surface. Never throws: a missing file is
+ * `not-found`; a module that throws on load or lacks a surface key is `unusable`.
+ */
+export function loadCurationStore(dir = scriptsDir()) {
+    return loadScript(join(dir, CURATION_STORE_SCRIPT_NAME), CURATION_STORE_SURFACE);
+}
+/**
+ * Why the store cannot be used, and the remedy: a package reinstall, since the
+ * CLI loads the package's own copy, which `devflow init` does not restore.
+ */
+export function formatCurationStoreUnavailable(error) {
+    switch (error.kind) {
+        case 'not-found': return 'curation store not found — reinstall devflow-kit';
+        case 'unusable': return 'curation store failed to load — reinstall devflow-kit';
+        default: {
+            const exhaustive = error;
+            return exhaustive;
+        }
+    }
+}
+//# sourceMappingURL=curation-store.js.map

package/dist/core/{learning-variants.js → curation-variants.js}

@@ -1,26 +1,26 @@
 /**
- * Learning-variant splitter: one compiled prompt body in, its learning-on and
- * learning-off variants out.
+ * Curation-variant splitter: one compiled prompt body in, its curation-on and
+ * curation-off variants out.
  *
  * Pure module, zero I/O. Every refusal is a Result; the exiting shell is
  * scripts/build-mds.ts, which renders these errors into the build's single exit.
  *
- * D-LEARNING-VARIANTS: when learning is off on a machine, the decisions text is
+ * D-LEARNING-VARIANTS: when curation is off on a machine, the decisions text is
  * ABSENT from every prompt it would have reached, not merely gated at run time.
- * The build therefore emits two variants of a prompt that carries learning text:
- * the learning-on variant at today's path (dist/commands/x.md, dist/agents/x.md)
- * and the learning-off variant at dist/learning-off/{commands,agents}/x.md, only
+ * The build therefore emits two variants of a prompt that carries curation text:
+ * the curation-on variant at today's path (dist/commands/x.md, dist/agents/x.md)
+ * and the curation-off variant at dist/curation-off/{commands,agents}/x.md, only
  * for a host that has an arm. A prompt with no arm has one variant and no
- * learning-off file.
+ * curation-off file.
  *
  * The arms are whole-line markers in the host or in a partial it expands:
  *
- *   <!-- learning:on -->     opens an arm that only the learning-on variant keeps
- *   <!-- learning:off -->    opens an arm that only the learning-off variant keeps;
+ *   <!-- curation:on -->     opens an arm that only the curation-on variant keeps
+ *   <!-- curation:off -->    opens an arm that only the curation-off variant keeps;
  *                            directly after an on arm it is that arm's else
- *   <!-- learning:end -->    closes the arm
+ *   <!-- curation:end -->    closes the arm
  *
- * A marker line matches LEARNING_MARKER_RE. It may be indented and may sit inside
+ * A marker line matches CURATION_MARKER_RE. It may be indented and may sit inside
  * a fenced block, a list, a define body or an agent's second frontmatter block,
  * because MDS passes an HTML comment through untouched. The splitter runs on the
  * COMPILED body, after the MDS compile, so it adds no compileFile call, no import
@@ -36,21 +36,26 @@
  * fence- and indent-aware `@if` (dean0x/mdscript#452). That swap, with the
  * @mdscript/mds upgrade it rides on proven byte-identical in dist/ and this module
  * deleted, is dean0x/devflow#439. The mapping is one to one: `on` becomes
- * `@if learning:`, `off` becomes `@else:` and `end` becomes `@end`. A standalone
- * `off` arm, with no on arm before it, becomes an `@if learning:` with an empty
+ * `@if curation:`, `off` becomes `@else:` and `end` becomes `@end`. A standalone
+ * `off` arm, with no on arm before it, becomes an `@if curation:` with an empty
  * body followed by `@else:`.
  *
- * What the splitter refuses, each as a LearningSplitError with the source line:
+ * What the splitter refuses, each as a CurationSplitError with the source line:
  *   - nesting: an `on` marker while an arm is open, or a second `off` in one arm;
  *   - an `end` with no open arm;
  *   - an arm still open at the end of the body;
  *   - an empty arm (no line with content between its marker and the next);
- *   - a stray marker: a line that names `<!-- learning:` but is not a whole-line
+ *   - a retired marker: a line that names the pre-rename spelling of the marker, in
+ *     any spacing or case, which would otherwise ship as prompt text;
+ *   - a stray marker: a line that names `<!-- curation:` but is not a whole-line
  *     marker, which would otherwise ship as prompt text.
  *
+ * The retired spelling is never accepted as an alias: the build fails on it, so a
+ * host that still carries it cannot ship a prompt with both variants silently equal.
+ *
  * Scope guarantee: this module answers one question (what are the two variants of
  * this body?) and one cheap one for the build to ask of a body that must carry no
- * arms (containsLearningMarker). It decides nothing about WHICH text belongs in an
+ * arms (containsCurationMarker). It decides nothing about WHICH text belongs in an
  * arm: that is authoring, and the guards over the built trees hold it.
  */
 function Ok(value) {
@@ -60,52 +65,65 @@ function Err(error) {
     return { ok: false, error };
 }
 /**
- * Repo-relative root of the learning-off variants.
+ * Repo-relative root of the curation-off variants.
  *
  * Exported because the build's orphan prune names this directory even when no
  * host carries an arm, which is exactly the case where every file in it is an
  * orphan, so it cannot be derived from the plan.
  */
-export const LEARNING_OFF_OUTPUT_DIR = 'dist/learning-off';
+export const CURATION_OFF_OUTPUT_DIR = 'dist/curation-off';
+/**
+ * Repo-relative root of the retired off tree, from before the rename.
+ *
+ * The build removes this folder whole after a clean run, so a checkout that built
+ * before the rename keeps no stale prompts there: nothing reads the folder, and the
+ * package would otherwise ship it.
+ */
+export const LEGACY_OFF_OUTPUT_DIR = 'dist/learning-off';
 /**
- * POSIX repo-relative path of the learning-off variant of an output file.
+ * POSIX repo-relative path of the curation-off variant of an output file.
  *
- * `fileName` is the already-validated basename the learning-on variant is written
+ * `fileName` is the already-validated basename the curation-on variant is written
  * under (`implement.md`), so the two variants of one host always share a name.
  */
-export function learningOffRelPath(kind, fileName) {
-    return `${LEARNING_OFF_OUTPUT_DIR}/${kind}/${fileName}`;
+export function curationOffRelPath(kind, fileName) {
+    return `${CURATION_OFF_OUTPUT_DIR}/${kind}/${fileName}`;
 }
 // ---------------------------------------------------------------------------
 // Markers
 // ---------------------------------------------------------------------------
 /**
- * A whole-line learning marker. The group captures `on`, `off` or `end`.
+ * A whole-line curation marker. The group captures `on`, `off` or `end`.
  *
  * Anchored at both ends with no nested quantifier, so a match is linear in the
  * line length. Leading and trailing space or tab is allowed; anything else on the
  * line is not a marker.
  */
-export const LEARNING_MARKER_RE = /^[ \t]*<!-- learning:(on|off|end) -->[ \t]*$/;
+export const CURATION_MARKER_RE = /^[ \t]*<!-- curation:(on|off|end) -->[ \t]*$/;
 /**
  * The fragment that makes a line a marker ATTEMPT: loose on spacing and case so a
  * malformed marker is caught rather than shipped. Every valid marker contains it.
  */
-const MARKER_FRAGMENT_RE = /<!--\s*learning\s*:/i;
-/** True when the text names a learning marker anywhere, valid or not. */
-export function containsLearningMarker(text) {
-    return MARKER_FRAGMENT_RE.test(text);
+const MARKER_FRAGMENT_RE = /<!--\s*curation\s*:/i;
+/**
+ * The same attempt test for the retired spelling of the marker. No spelling of it is
+ * valid, so a line that matches is always refused.
+ */
+const LEGACY_MARKER_FRAGMENT_RE = /<!--\s*learning\s*:/i;
+/** True when the text names a marker anywhere, in the current or the retired spelling, valid or not. */
+export function containsCurationMarker(text) {
+    return MARKER_FRAGMENT_RE.test(text) || LEGACY_MARKER_FRAGMENT_RE.test(text);
 }
 function markerOf(line) {
     // A CRLF body carries the carriage return on the line; it is not part of the marker.
     const bare = line.endsWith('\r') ? line.slice(0, -1) : line;
-    const match = LEARNING_MARKER_RE.exec(bare);
+    const match = CURATION_MARKER_RE.exec(bare);
     return match === null ? null : match[1];
 }
 /** The longest stretch of a stray line a refusal quotes. */
 const STRAY_QUOTE_MAX = 80;
 /**
- * Split a compiled body into its learning-on and learning-off variants.
+ * Split a compiled body into its curation-on and curation-off variants.
  *
  * Total and pure: the same input gives the same output, and a refusal is a
  * Result. The loop is one pass over the body's lines, so its bound is the body's
@@ -115,7 +133,7 @@ const STRAY_QUOTE_MAX = 80;
  * refused as empty, because it would add blank lines to one variant and nothing to
  * the other, which is a mistake rather than a design.
  */
-export function splitLearningVariants(body) {
+export function splitCurationVariants(body) {
     const lines = body.split('\n');
     const on = [];
     const off = [];
@@ -130,6 +148,9 @@ export function splitLearningVariants(body) {
         const lineNo = index + 1;
         const marker = markerOf(line);
         if (marker === null) {
+            if (LEGACY_MARKER_FRAGMENT_RE.test(line)) {
+                return Err({ kind: 'legacy-marker', line: lineNo, text: line.trim().slice(0, STRAY_QUOTE_MAX) });
+            }
             if (MARKER_FRAGMENT_RE.test(line)) {
                 return Err({ kind: 'stray-marker', line: lineNo, text: line.trim().slice(0, STRAY_QUOTE_MAX) });
             }
@@ -186,28 +207,31 @@ export function splitLearningVariants(body) {
  * fall through into a message that does not describe it. Shared by the build and
  * the tests, so the text asserted is the text shipped.
  */
-export function describeLearningSplitError(error) {
+export function describeCurationSplitError(error) {
     switch (error.kind) {
         case 'nested-arm':
-            return (`line ${error.line}: a learning:on marker inside the ${error.arm} arm opened at line ` +
-                `${error.openedAt} — arms do not nest; close it with learning:end first`);
+            return (`line ${error.line}: a curation:on marker inside the ${error.arm} arm opened at line ` +
+                `${error.openedAt} — arms do not nest; close it with curation:end first`);
         case 'repeated-off':
-            return (`line ${error.line}: a second learning:off marker inside the off arm opened at line ` +
+            return (`line ${error.line}: a second curation:off marker inside the off arm opened at line ` +
                 `${error.openedAt} — an arm has at most one else`);
         case 'unopened-end':
-            return `line ${error.line}: a learning:end marker with no open arm`;
+            return `line ${error.line}: a curation:end marker with no open arm`;
         case 'unclosed-arm':
-            return `the ${error.arm} arm opened at line ${error.openedAt} is never closed with learning:end`;
+            return `the ${error.arm} arm opened at line ${error.openedAt} is never closed with curation:end`;
         case 'empty-arm':
             return (`lines ${error.openedAt}-${error.closedAt}: the ${error.arm} arm holds no line with content — ` +
                 `delete the arm or put its text inside it`);
+        case 'legacy-marker':
+            return (`line ${error.line}: "${error.text}" uses the retired learning marker — rename it to ` +
+                `<!-- curation:on -->, <!-- curation:off --> or <!-- curation:end -->`);
         case 'stray-marker':
-            return (`line ${error.line}: "${error.text}" names a learning marker but is not one — a marker ` +
-                `is a whole line, exactly <!-- learning:on -->, <!-- learning:off --> or <!-- learning:end -->`);
+            return (`line ${error.line}: "${error.text}" names a curation marker but is not one — a marker ` +
+                `is a whole line, exactly <!-- curation:on -->, <!-- curation:off --> or <!-- curation:end -->`);
         default: {
             const unhandled = error;
-            return `unhandled learning split error ${JSON.stringify(unhandled)}`;
+            return `unhandled curation split error ${JSON.stringify(unhandled)}`;
         }
     }
 }
-//# sourceMappingURL=learning-variants.js.map
+//# sourceMappingURL=curation-variants.js.map

package/dist/core/echo-value.js

@@ -0,0 +1,48 @@
+/**
+ * Render an untrusted value for a terminal message.
+ *
+ * A neutral home for the sanitizer that every parser echoing a rejected value
+ * shares (the tracker provider and the gate level today), so no parser imports
+ * another feature's module just to reach it.
+ */
+/** Longest rejected value echoed back to the terminal, in CODE POINTS, unless the caller names another. */
+const MAX_ECHOED_VALUE = 40;
+/**
+ * Render an untrusted token for a terminal message.
+ *
+ * Rejected values are echoed so the user can see what they typed, so they are
+ * third-party input at a display sink: control characters (terminal escapes,
+ * BEL, newlines) are replaced and the value is truncated.
+ *
+ * `maxLength` is the cut, in code points. A caller that echoes a whole message (a name
+ * inside a sentence) names a longer bound; anything that is not a positive integer takes
+ * the default, so the render stays bounded whatever a caller passes.
+ *
+ * Takes `unknown`, and a non-string renders as its TYPE: the never-throws
+ * contract of the callers has to hold for what reaches this sink, not
+ * only for what the signature says — a caller reads hand-editable
+ * files, and a caller-side guard is one edit from being gone. Naming the type
+ * also keeps the render total, where `String()` would hand control to a
+ * caller-supplied `toString` — itself both a throw path and an echo path this
+ * function exists to close.
+ */
+export function describeEchoedValue(raw, maxLength = MAX_ECHOED_VALUE) {
+    if (typeof raw !== 'string')
+        return `<${raw === null ? 'null' : typeof raw}>`;
+    const limit = Number.isInteger(maxLength) && maxLength > 0 ? maxLength : MAX_ECHOED_VALUE;
+    // The class is written with ESCAPES, never literal control bytes. A raw NUL
+    // makes grep classify this whole file as binary — it prints "Binary file
+    // matches" and skips the lines — so every grep-based sweep over src/core/
+    // silently stops covering the file while still exiting 0. Pinned by
+    // tests/guards/no-control-bytes.test.ts.
+    // C0, DEL and C1: a terminal acts on all three (U+009B is the one-character CSI).
+    // eslint-disable-next-line no-control-regex
+    const stripped = raw.replace(/[\x00-\x1f\x7f-\x9f]/g, '?');
+    // Cut by CODE POINT. `slice` cuts UTF-16 code units, so a cut landing inside an
+    // astral character (emoji, CJK ext-B) emits the lone surrogate half of it.
+    const points = [...stripped];
+    return points.length > limit
+        ? `${points.slice(0, limit).join('')}…`
+        : stripped;
+}
+//# sourceMappingURL=echo-value.js.map

package/dist/core/evidence-policy.js

@@ -102,7 +102,7 @@ function surfaceMismatches(value, surface) {
  * throws: a missing file is `not-found`; a module that throws on load or lacks a
  * surface key is `unusable`. The caller's type parameter is justified by the
  * surface check, which `satisfies` ties to the interface's keys. Exported for
- * src/core/learning-store.ts, which loads the learning store the same way.
+ * src/core/curation-store.ts, which loads the curation store the same way.
  */
 export function loadScript(scriptPath, surface) {
     let loaded;
@@ -331,15 +331,27 @@ export function repoComplianceStatusLines(loaded, opts) {
  * tracked by git, or null (D-PERSONAL-UNTRACKED). The resolver ignores such a file
  * and says so on stderr, but prompts run it with stderr discarded, so a status
  * command is where the user sees why their personal settings have no effect.
+ *
+ * Takes the ONE resolved result, so a caller that already holds it adds no second
+ * resolve (each resolve forks git).
+ */
+export function trackedConfigWarning(settings) {
+    if (!settings.personalTracked)
+        return null;
+    const file = settingsSourceFile('personal');
+    return `Git tracks an entry at or under ${file}, so devflow ignores that file. It holds personal settings. ` +
+        'Find the entry in the output of: git ls-files. Untrack it with: git rm --cached <entry>. ' +
+        'Then check the file contents, or delete the file. ' +
+        'Untracking leaves the committed bytes on disk as your personal file.';
+}
+/**
+ * {@link trackedConfigWarning} for a caller that holds the loaded module and not a
+ * resolved result: it resolves once and returns null when the module is unusable.
  */
 export function personalConfigTrackedWarning(loaded, opts) {
     if (!loaded.ok)
         return null;
-    if (!loaded.value.resolveSettings(opts).personalTracked)
-        return null;
-    const file = settingsSourceFile('personal');
-    return `${file} is tracked by git, so devflow ignores it — it holds personal settings. ` +
-        `Untrack it with: git rm --cached ${file}`;
+    return trackedConfigWarning(loaded.value.resolveSettings(opts));
 }
 /** The policies the hint maps, in the order it prints them. */
 const HINT_POLICIES = ['standard', 'required'];