@ctxr/skill-llm-wiki 1.0.2 → 1.2.0

package/scripts/cli.mjs

@@ -326,9 +326,38 @@ Layout-mode flags (build/extend/rebuild/fix/join):
   --target <path>                  Explicit destination (required for hosted)
 
 Tiered-AI flags:
-  --quality-mode tiered-fast|claude-first|tier0-only
+  --quality-mode tiered-fast|claude-first|deterministic
                                    Default: tiered-fast (TF-IDF → embeddings
-                                   → Claude ladder). See guide/tiered-ai.md.
+                                   → Claude ladder). The 'deterministic' mode
+                                   resolves every decision algorithmically
+                                   (no Tier 2 calls) for byte-reproducible
+                                   builds. See guide/tiered-ai.md.
+
+Post-convergence enforcement flags (build/rebuild):
+  --fanout-target <N>              Post-convergence phase ATTEMPTS to
+                                   sub-cluster any directory whose movable
+                                   leaf count exceeds N × 1.5 (subdirs aren't
+                                   counted — the rebalance can only carve
+                                   clusters from leaves, so subdir-heavy
+                                   dirs are un-actionable). An overfull dir
+                                   is left unchanged when no coherent
+                                   cluster is detected (leaves too diverse
+                                   or too few). N must be an integer in
+                                   [2, 100]. No-op when omitted.
+  --max-depth <D>                  Post-convergence phase flattens any
+                                   single-child passthrough deeper than D. D
+                                   must be an integer in [1, 10]. No-op when
+                                   omitted.
+  --soft-dag-parents               Post-convergence phase synthesises
+                                   soft-parent pointers in each leaf's
+                                   parents[] based on TF-IDF cosine
+                                   similarity against candidate category
+                                   directories. Leaves appear in multiple
+                                   index.md entries[] (DAG view) rather
+                                   than only their direct parent. Uses
+                                   SOFT_PARENT_AFFINITY_THRESHOLD (0.35)
+                                   and caps at SOFT_PARENT_MAX_PER_LEAF (3)
+                                   per leaf. No-op when omitted.
 
 UX flags:
   --no-prompt                      Never prompt; fail loud on ambiguity
@@ -378,6 +407,9 @@ const FLAG_WITH_VALUE = new Set([
   "--to",
   "--canonical",
   "--quality-mode",
+  "--fanout-target",
+  "--max-depth",
+  "--id-collision",
 ]);
 const FLAG_BOOLEAN = new Set([
   "--no-prompt",
@@ -386,6 +418,7 @@ const FLAG_BOOLEAN = new Set([
   "--accept-dirty",
   "--accept-foreign-target",
   "--review",
+  "--soft-dag-parents",
 ]);
 
 function parseSubArgv(raw) {
@@ -815,12 +848,69 @@ async function main() {
     }
     const opId = newOpId(cmd);
     const startedIso = new Date().toISOString();
+    // X.9 progress: stream each orchestrator phase's `record()`
+    // output to stderr as it fires. On by default for interactive
+    // use; suppressed in JSON mode so stderr stays reserved for
+    // structured JSON diagnostics/errors (build/rebuild/fix/join
+    // still print their human-readable summary to stdout under
+    // --json, but a consumer tailing stderr under --json expects
+    // it to be empty on success or carry only structured
+    // diagnostics — progress breadcrumbs would mix into that
+    // channel). Also suppressed via `LLM_WIKI_NO_PROGRESS=1` for
+    // CI / hermetic runs that want the pre-X.9 silent shape.
+    // Progress goes to stderr (never stdout) so consumers piping
+    // the command's stdout don't conflate phase chatter with the
+    // final op-summary payload.
+    const suppressProgress =
+      jsonMode || process.env.LLM_WIKI_NO_PROGRESS === "1";
+    // A closed-stderr scenario (downstream pipe consumer that
+    // drops the stderr pipe, e.g. `… | head`) surfaces two ways:
+    // a synchronous throw on `.write()` (try/catch below), and
+    // an async `'error'` event with code EPIPE that the default
+    // Node handler escalates to an unhandled exception. Attach a
+    // best-effort one-time 'error' listener to swallow EPIPE
+    // while progress is enabled; other stream errors still
+    // surface via Node's default handler so we aren't masking
+    // bugs unrelated to the progress stream.
+    let stderrEpipeSilenced = false;
+    const onProgress = suppressProgress
+      ? null
+      : (phase) => {
+          if (!stderrEpipeSilenced) {
+            stderrEpipeSilenced = true;
+            try {
+              process.stderr.on("error", (err) => {
+                if (err && err.code === "EPIPE") return;
+                // Re-emit non-EPIPE errors so we don't hide real
+                // problems — Node's default handler will decide.
+                throw err;
+              });
+            } catch {
+              /* attach failed — progress reporter will best-effort */
+            }
+          }
+          // `.destroyed` / `.writableEnded` guards let us skip the
+          // write before it would throw, which is cheaper than
+          // catching the exception and matches the behaviour on
+          // an already-closed stream.
+          if (process.stderr.destroyed || process.stderr.writableEnded) {
+            return;
+          }
+          try {
+            process.stderr.write(
+              `[${opId} ${phase.index}] ${phase.name}: ${phase.summary}\n`,
+            );
+          } catch {
+            /* Best-effort — a closed stderr shouldn't halt the op. */
+          }
+        };
     let result;
     try {
       result = await runOperation(plan, {
         opId,
         source: plan.source,
         startedIso,
+        onProgress,
       });
     } catch (err) {
       if (err instanceof NonInteractiveError) {