harnery 0.4.0 → 0.5.0

package/dist/lib/completion/zsh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zsh.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/zsh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,WAAW,CAAC;AAwBzE,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAsGtE"}
+{"version":3,"file":"zsh.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/zsh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,WAAW,CAAC;AAwBzE,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAsGtE;AAOD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAyB1D"}

package/dist/lib/completion/zsh.js

@@ -129,6 +129,39 @@ function truncate(s, n) {
         return "";
     return s.length > n ? `${s.slice(0, n - 1)}…` : s;
 }
+/**
+ * DYNAMIC zsh completion: a thin, tree-independent shim that calls
+ * `<bin> __complete-line` on every <Tab> (see bash.ts generateBashDynamic for
+ * the rationale). Candidate lines are `value\tdescription`; the shim converts
+ * the tab to `:` so `_describe` renders descriptions. The trailing `\x1f:<n>`
+ * line carries the directive (bit 0 = file fallback → `_files`).
+ */
+export function generateZshDynamic(binName) {
+    const fn = fnPrefix(binName);
+    return `#compdef ${binName}
+# ${binName} zsh completion (dynamic; install once, never stale). Do not edit.
+${fn}() {
+  emulate -L zsh
+  local line directive=0
+  local -a raw display
+  raw=( "\${(@f)$(${binName} __complete-line $((CURRENT-1)) -- "\${words[@]}" 2>/dev/null)}" )
+  for line in $raw; do
+    [ -z "$line" ] && continue
+    if [[ "$line" == $'\\x1f:'* ]]; then
+      directive="\${line#$'\\x1f:'}"
+    else
+      display+=( "\${line//$'\\t'/:}" )
+    fi
+  done
+  if (( directive & 1 )); then
+    _files
+    return
+  fi
+  _describe -t values 'completions' display
+}
+compdef ${fn} ${binName}
+`;
+}
 /**
  * The driver walks `$words` to determine the current command path, then
  * dispatches to subcommand / option / value completion. `fn` is the

package/dist/lib/docs-lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAYA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C,GAAG,IAAI,CAIP;AAaD;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAkVD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAoBlE"}
+{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAYA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C,GAAG,IAAI,CAIP;AAaD;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAuVD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAoBlE"}

package/dist/lib/docs-lint.js

@@ -204,6 +204,12 @@ function checkNamingConvention(repoName, _repoPath, files) {
         // Allowlisted names
         if (ROOT_FILE_ALLOWLIST.has(name))
             continue;
+        // Leading-underscore files are deliberate templates / meta files
+        // (e.g. _template.md), not content. The underscore is a convention
+        // marking "copy me, don't read me as a real doc", so exempt them
+        // from naming discipline rather than forcing kebab-case.
+        if (name.startsWith("_"))
+            continue;
         // Dated files (audits/issues)
         if (DATED_FILE_PATTERN.test(name))
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Multi-agent coordination + harness adapters + portable CLI utilities for Claude Code / Cursor / Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",

package/src/commands/completion.ts

@@ -4,9 +4,15 @@ import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import {
   type CompletionContextLookup,
+  type CompletionProviderRunner,
+  encodeResult,
   generateBash,
+  generateBashDynamic,
   generateFish,
+  generateFishDynamic,
   generateZsh,
+  generateZshDynamic,
+  resolveCompletions,
   walkProgram,
 } from "../lib/completion/index.ts";
 
@@ -39,27 +45,39 @@ export function registerCompletionCommand(
       "Shell tab-completion. Emit a script per shell or install to the standard location.",
     );
 
+  const dynamicHint =
+    "Emit a thin shim that calls the binary at tab-time (never goes stale; install once)";
+
   root
     .command("bash")
     .description("Emit bash completion script to stdout")
-    .action(() => {
-      const out = generateBash(walkProgram(program, lookup), program.name());
+    .option("--dynamic", dynamicHint)
+    .action((opts: { dynamic?: boolean }) => {
+      const out = opts.dynamic
+        ? generateBashDynamic(program.name())
+        : generateBash(walkProgram(program, lookup), program.name());
       process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
     });
 
   root
     .command("zsh")
     .description("Emit zsh completion script to stdout")
-    .action(() => {
-      const out = generateZsh(walkProgram(program, lookup), program.name());
+    .option("--dynamic", dynamicHint)
+    .action((opts: { dynamic?: boolean }) => {
+      const out = opts.dynamic
+        ? generateZshDynamic(program.name())
+        : generateZsh(walkProgram(program, lookup), program.name());
       process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
     });
 
   root
     .command("fish")
     .description("Emit fish completion script to stdout")
-    .action(() => {
-      const out = generateFish(walkProgram(program, lookup), program.name());
+    .option("--dynamic", dynamicHint)
+    .action((opts: { dynamic?: boolean }) => {
+      const out = opts.dynamic
+        ? generateFishDynamic(program.name())
+        : generateFish(walkProgram(program, lookup), program.name());
       process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
     });
 
@@ -69,6 +87,7 @@ export function registerCompletionCommand(
     .option("--shell <name>", "bash | zsh | fish (default: auto-detect from $SHELL)")
     .option("--path <file>", "Override destination path")
     .option("--print-path", "Print the destination path and exit (no write)")
+    .option("--dynamic", `${dynamicHint} (recommended)`)
     .action(async (opts: InstallOpts) => {
       await installCompletion(program, opts, lookup);
     });
@@ -92,12 +111,39 @@ export function registerCompletionCommand(
     });
   // Keep TS happy that the variable is used.
   void hidden;
+
+  // Hidden internal entry for DYNAMIC completion: the thin shim passes the live
+  // command line (cursor index + all words after `--`) and we compute the full
+  // candidate set from the live command tree. `--` stops option parsing so
+  // words like `-h` reach the variadic instead of being read as our flags.
+  const hiddenLine = program
+    .command("__complete-line <cword> [words...]", { hidden: true })
+    .description("Internal: full-line completion callback for the dynamic shell shim")
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .action(async (cword: string, words: string[] | undefined) => {
+      try {
+        const result = await resolveCompletions(
+          program,
+          words ?? [],
+          Number.parseInt(cword, 10) || 0,
+          lookup,
+          runProvider as CompletionProviderRunner,
+        );
+        process.stdout.write(encodeResult(result)); // lint-ok-emission: shell callback; the encoded candidate/directive stream is the contract with the shim.
+      } catch {
+        // Never break the user's tab: emit just the file-fallback directive.
+        process.stdout.write("\x1f:1\n"); // lint-ok-emission: shell callback fallback directive.
+      }
+    });
+  void hiddenLine;
 }
 
 interface InstallOpts {
   shell?: string;
   path?: string;
   printPath?: boolean;
+  dynamic?: boolean;
 }
 
 async function installCompletion(
@@ -117,16 +163,23 @@ async function installCompletion(
     return;
   }
 
+  const name = program.name();
   let content: string;
   switch (shell) {
     case "bash":
-      content = generateBash(walkProgram(program, lookup), program.name());
+      content = opts.dynamic
+        ? generateBashDynamic(name)
+        : generateBash(walkProgram(program, lookup), name);
       break;
     case "zsh":
-      content = generateZsh(walkProgram(program, lookup), program.name());
+      content = opts.dynamic
+        ? generateZshDynamic(name)
+        : generateZsh(walkProgram(program, lookup), name);
       break;
     case "fish":
-      content = generateFish(walkProgram(program, lookup), program.name());
+      content = opts.dynamic
+        ? generateFishDynamic(name)
+        : generateFish(walkProgram(program, lookup), name);
       break;
     default:
       process.stderr.write(`Unknown shell: ${shell}\n`); // lint-ok-emission: install-time error, see above.

package/src/core/agents/rules/claim-conflict.ts

@@ -101,7 +101,15 @@ export function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResu
   const hasFreshPeers = otherPeers.some(
     (p) => isFresh(p.last_heartbeat) && p.files_touched.length > 0,
   );
-  if (hasFreshPeers && myPeer && myPeer.files_touched.length > 0) {
+  // Re-editing a path already in our own files_touched acquires no new lock
+  // edge, so it can't create a circular wait — the ordering rule must not block
+  // it. Without this exemption, an agent that edits a higher-sorting file and
+  // then makes a second pass over an already-held lower-sorting file gets a
+  // spurious ordering_violation (the dominant friction source under concurrency:
+  // both agent-Gibson holding README.md and agent-Ophelia holding AGENTS.md were
+  // blocked re-editing those held files after touching a higher path, 2026-07-03).
+  const alreadyHeld = myPeer?.files_touched.includes(req.path) ?? false;
+  if (hasFreshPeers && myPeer && myPeer.files_touched.length > 0 && !alreadyHeld) {
     // Only ACTIVE (uncommitted) edits should constrain lock ordering. A claim on
     // a committed-clean file is a finished edit, not a held lock, so it must not
     // wall off a lower-sorted acquisition. Without this, a long session
@@ -118,7 +126,7 @@ export function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResu
           allow: false,
           exit_code: 2,
           rule: "claim.ordering_violation",
-          reason: `Cannot acquire ${req.path} while holding ${highest} (claim ordering rule: paths must be acquired in sorted order). Release the higher claim first.`,
+          reason: `Cannot acquire ${req.path}: you already hold ${highest}, which sorts after it (claim ordering rule: acquire paths in sorted order to prevent deadlock between concurrent agents). Fix by editing in sorted order, or by committing ${highest} first, since a committed-clean file no longer blocks and is auto-pruned.`,
         };
       }
       // Every blocker is a finished (committed-clean) edit: prune them so they

package/src/core/hooks/cli.ts

@@ -42,6 +42,7 @@ import {
 } from "./effects/index.ts";
 import { emit } from "./events/emit.ts";
 import type { Harness } from "./events/schema.ts";
+import { canonicalize } from "./guard-path.ts";
 import { detectHarness } from "./harness/detect.ts";
 import {
   extractBashCommand,
@@ -774,7 +775,9 @@ async function runPreToolUseGuard(
   harness: Harness,
 ): Promise<void> {
   const toolName = (data.tool_name as string | undefined) ?? "";
-  const targets = collectGuardTargets(toolName, data).map((p) => canonicalize(coordRoot, p));
+  const targets = collectGuardTargets(toolName, data)
+    .map((p) => canonicalize(coordRoot, p))
+    .filter((p): p is string => p !== null);
   if (targets.length === 0) return;
 
   const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
@@ -822,13 +825,6 @@ async function runPreToolUseGuard(
 /** Canonicalize a path to monorepo-relative form. Absolute paths under
  * coordRoot get the prefix stripped; relative paths pass through (assumed
  * already canonical). */
-function canonicalize(coordRoot: string, p: string): string {
-  if (!p) return p;
-  if (p.startsWith(`${coordRoot}/`)) return p.slice(coordRoot.length + 1);
-  if (p === coordRoot) return ".";
-  return p;
-}
-
 /** Pull the candidate path(s) out of a write-tool payload. Empty array when
  * the tool isn't a write or no path could be derived. */
 function collectGuardTargets(toolName: string, data: Record<string, unknown>): string[] {

package/src/core/hooks/guard-path.ts

@@ -0,0 +1,34 @@
+/**
+ * Canonicalize a write-tool target path for the claim guard.
+ *
+ * Returns the monorepo-relative path, or `null` when the target lies OUTSIDE the
+ * repo (an absolute path not under coordRoot, e.g. a `/tmp` scratchpad or other
+ * session-temp file).
+ *
+ * The claim system is intentionally repo-scoped: it coordinates monorepo files,
+ * not arbitrary absolute paths, so the guard skips out-of-repo targets. Skipping
+ * them is right on two counts. First, it keeps non-repo paths out of a
+ * heartbeat's `files_touched`. Second, the ordering rule compares raw path
+ * strings, and an absolute `/tmp/…` sorts before every repo-relative path
+ * (`/` = 0x2F < any letter), so without this a scratchpad write would spuriously
+ * "block" a legitimately-held repo file. Returning null keeps such paths out of
+ * the claim system entirely.
+ *
+ * Accepted tradeoff: this also means shared out-of-repo files (a user-level
+ * memory or plans directory) are not coordinated across agents. The alternative,
+ * normalizing every path to one consistent key so those stay coordinated, was
+ * rejected as gold-plating a rare, merge-disciplined race in a deadlock-critical
+ * path. Coordinate shared state by keeping it in the repo, not out of it.
+ *
+ * Relative inputs are assumed already-repo-relative (Codex `apply_patch` emits
+ * cwd-relative paths). The in-repo check requires the `<root>/` separator, so a
+ * sibling dir that merely shares a prefix (`/repo-other` vs `/repo`) is treated
+ * as out-of-repo, not stripped.
+ */
+export function canonicalize(coordRoot: string, p: string): string | null {
+  if (!p) return null;
+  if (p === coordRoot) return ".";
+  if (p.startsWith(`${coordRoot}/`)) return p.slice(coordRoot.length + 1);
+  if (p.startsWith("/")) return null; // absolute + not under coordRoot → out-of-repo
+  return p; // relative → treat as repo-relative
+}

package/src/lib/completion/bash.ts

@@ -162,6 +162,42 @@ function bashEscape(s: string): string {
  * to subcommand / option / value completion. `fn` is the function-name prefix
  * and `binName` is the CLI name used for the `__complete` callback.
  */
+/**
+ * DYNAMIC bash completion: a thin, tree-independent shim. Instead of baking the
+ * command tree into case-tables (which go stale on any command/flag change),
+ * it hands the live command line to `<bin> __complete-line` on every <Tab> and
+ * lets the binary — which always knows its own current tree — answer. Install
+ * once; never regenerate. The trailing `\x1f:<n>` line carries the directive
+ * bitmask (bit 0 = fall back to file completion).
+ */
+export function generateBashDynamic(binName: string): string {
+  const fn = fnPrefix(binName);
+  return `# ${binName} bash completion (dynamic; install once, never stale). Do not edit.
+# Source via:  eval "$(${binName} completion bash --dynamic)"
+${fn}() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  local raw line directive=0
+  local -a cands=()
+  raw="$(${binName} __complete-line "$COMP_CWORD" -- "\${COMP_WORDS[@]}" 2>/dev/null)" || return
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    if [ "\${line:0:2}" = $'\\x1f:' ]; then
+      directive="\${line:2}"
+    else
+      cands+=( "\${line%%$'\\t'*}" )
+    fi
+  done <<< "$raw"
+  if (( directive & 1 )); then
+    COMPREPLY=( $(compgen -f -- "$cur") )
+    return
+  fi
+  local IFS=$'\\n'
+  COMPREPLY=( $(compgen -W "\${cands[*]}" -- "$cur") )
+}
+complete -F ${fn} ${binName}
+`;
+}
+
 function bashDriver(fn: string, binName: string): string {
   return `${fn}() {
   local cur prev words cword

package/src/lib/completion/fish.ts

@@ -67,6 +67,28 @@ function valueAction(
   return { flag: "-r", arg: "" };
 }
 
+/**
+ * DYNAMIC fish completion: a thin, tree-independent shim that calls
+ * `<bin> __complete-line` on every <Tab> (see bash.ts generateBashDynamic for
+ * the rationale). Fish renders `value\tdescription` lines natively, so the
+ * helper just strips the trailing `\x1f:<n>` directive line. Note: fish's
+ * declarative `complete -a` cannot switch to file completion from inside the
+ * helper, so the File directive is a no-op here — use static fish completion
+ * (`completion fish`) if you need file fallback on a path-valued positional.
+ */
+export function generateFishDynamic(binName: string): string {
+  const fn = `__${binName.replace(/[^a-zA-Z0-9_]/g, "_")}_complete`;
+  return `# ${binName} fish completion (dynamic; install once, never stale). Do not edit.
+# Source via:  ${binName} completion fish --dynamic | source
+function ${fn}
+  set -l toks (commandline -opc)
+  set -l cur (commandline -ct)
+  ${binName} __complete-line (count $toks) -- $toks $cur 2>/dev/null | string match -rv '^\\x1f:'
+end
+complete -c ${binName} -f -a '(${fn})'
+`;
+}
+
 export function generateFish(root: CommandSpec, binName: string): string {
   const out: string[] = [];
   out.push(

package/src/lib/completion/index.ts

@@ -1,5 +1,14 @@
-export { generateBash } from "./bash.js";
-export { generateFish } from "./fish.js";
+export { generateBash, generateBashDynamic } from "./bash.js";
+export { generateFish, generateFishDynamic } from "./fish.js";
+export {
+  type Candidate,
+  type CompletionProviderRunner,
+  type CompletionResult,
+  DIRECTIVE_PREFIX,
+  Directive,
+  encodeResult,
+  resolveCompletions,
+} from "./resolve.js";
 export {
   type CommandSpec,
   type CompletionContextLookup,
@@ -7,4 +16,4 @@ export {
   type PositionalSpec,
   walkProgram,
 } from "./walk.js";
-export { generateZsh } from "./zsh.js";
+export { generateZsh, generateZshDynamic } from "./zsh.js";

package/src/lib/completion/resolve.ts

@@ -0,0 +1,210 @@
+/**
+ * Runtime completion resolver — the authoritative, in-process answer to
+ * "what should I suggest at this cursor position?".
+ *
+ * The static bash/zsh/fish generators bake the whole command tree into shell
+ * case-tables, which go stale the moment a command/flag is added (the script
+ * must be regenerated + reinstalled). The DYNAMIC completion path instead
+ * installs a thin, tree-independent shim that, on every <Tab>, hands the live
+ * command line back to the binary and calls THIS function. Because the binary
+ * always knows its own current command tree, a dynamic shim never goes stale —
+ * install once, ever.
+ *
+ * This mirrors the path-walking the static bash driver does, but in one place
+ * and in TypeScript, so all three shells share identical behavior. It is
+ * deliberately decoupled from Commander internals via the CommandSpec tree
+ * (walkProgram), exactly like the static generators.
+ */
+
+import type { Command } from "commander";
+import { type CommandSpec, type CompletionContextLookup, walkProgram } from "./walk.js";
+
+/** Bitmask of post-processing hints for the shell shim (Cobra-style). */
+export const Directive = {
+  /** Use the returned candidates as completion values. */
+  Default: 0,
+  /** No candidates apply here — the shell should fall back to file completion. */
+  File: 1,
+} as const;
+
+export interface Candidate {
+  value: string;
+  description?: string;
+}
+
+export interface CompletionResult {
+  candidates: Candidate[];
+  directive: number;
+}
+
+/** Provider runner injected by the host CLI (same contract as `__complete`). */
+export type CompletionProviderRunner = (provider: string, partial: string) => Promise<string[]>;
+
+interface PathTables {
+  subcommandsByPath: Map<string, CommandSpec[]>;
+  /** path → flag (long or short) → spec, for both forms. */
+  optionsByPath: Map<string, CommandSpec["options"]>;
+  positionalsByPath: Map<string, CommandSpec["positionals"]>;
+}
+
+function buildTables(root: CommandSpec): PathTables {
+  const subcommandsByPath = new Map<string, CommandSpec[]>();
+  const optionsByPath = new Map<string, CommandSpec["options"]>();
+  const positionalsByPath = new Map<string, CommandSpec["positionals"]>();
+  const walk = (s: CommandSpec): void => {
+    subcommandsByPath.set(s.path, s.subcommands);
+    optionsByPath.set(s.path, s.options);
+    positionalsByPath.set(s.path, s.positionals);
+    for (const sub of s.subcommands) walk(sub);
+  };
+  walk(root);
+  return { subcommandsByPath, optionsByPath, positionalsByPath };
+}
+
+function optionAt(tables: PathTables, path: string, flag: string) {
+  const opts = tables.optionsByPath.get(path) ?? [];
+  return opts.find((o) => o.long === flag || o.short === flag);
+}
+
+function isKnownSubcommand(tables: PathTables, path: string, name: string): boolean {
+  return (tables.subcommandsByPath.get(path) ?? []).some((c) => c.name === name);
+}
+
+/**
+ * Walk the words before the cursor to determine the current command path,
+ * skipping options and the values they consume (mirrors the static driver).
+ * Returns the resolved command path ("" = root).
+ */
+function resolvePath(tables: PathTables, words: string[], cword: number): string {
+  let path = "";
+  let i = 1; // words[0] is the bin name
+  while (i < cword) {
+    const w = words[i] ?? "";
+    if (w.startsWith("-")) {
+      const opt = optionAt(tables, path, w);
+      if (opt?.takesValue) i += 1; // skip the option's value
+    } else if (isKnownSubcommand(tables, path, w)) {
+      path = path ? `${path} ${w}` : w;
+    }
+    i += 1;
+  }
+  return path;
+}
+
+/** Count positional args consumed at the resolved path (non-option, non-subcommand words). */
+function positionalIndex(tables: PathTables, words: string[], cword: number): number {
+  let seen = "";
+  let after = 0;
+  let j = 1;
+  while (j < cword) {
+    const w = words[j] ?? "";
+    if (w.startsWith("-")) {
+      const opt = optionAt(tables, seen, w);
+      if (opt?.takesValue) j += 1;
+    } else if (isKnownSubcommand(tables, seen, w)) {
+      seen = seen ? `${seen} ${w}` : w;
+    } else {
+      after += 1;
+    }
+    j += 1;
+  }
+  return after;
+}
+
+/** Resolve the value source (enum / dynamic-provider / file) for a value slot. */
+async function valueCandidates(
+  source: { valueChoices?: string[]; dynamicProvider?: string },
+  partial: string,
+  runProvider: CompletionProviderRunner,
+): Promise<CompletionResult> {
+  if (source.dynamicProvider) {
+    try {
+      const values = await runProvider(source.dynamicProvider, partial);
+      return { candidates: values.map((value) => ({ value })), directive: Directive.Default };
+    } catch {
+      return { candidates: [], directive: Directive.File };
+    }
+  }
+  if (source.valueChoices && source.valueChoices.length > 0) {
+    return {
+      candidates: source.valueChoices.map((value) => ({ value })),
+      directive: Directive.Default,
+    };
+  }
+  // A value is expected but we have nothing to suggest → let the shell try files.
+  return { candidates: [], directive: Directive.File };
+}
+
+/**
+ * Compute completion candidates for `words` with the cursor at `cword`.
+ * `words[0]` is the bin name; `words[cword]` is the (possibly empty) token
+ * being completed. The shell shim does the final prefix-filtering against that
+ * token, so this returns the full candidate set for the slot.
+ */
+export async function resolveCompletions(
+  program: Command,
+  words: string[],
+  cword: number,
+  lookup: CompletionContextLookup,
+  runProvider: CompletionProviderRunner,
+): Promise<CompletionResult> {
+  const tables = buildTables(walkProgram(program, lookup));
+  const path = resolvePath(tables, words, cword);
+  const cur = words[cword] ?? "";
+  const prev = cword > 0 ? (words[cword - 1] ?? "") : "";
+
+  // Case 1: previous word is an option that takes a value → complete the value.
+  if (prev.startsWith("-")) {
+    const opt = optionAt(tables, path, prev);
+    if (opt?.takesValue) return valueCandidates(opt, cur, runProvider);
+  }
+
+  // Case 2: completing an option name (cur starts with "-").
+  if (cur.startsWith("-")) {
+    const opts = tables.optionsByPath.get(path) ?? [];
+    const candidates: Candidate[] = [];
+    for (const o of opts) {
+      if (o.long) candidates.push({ value: o.long, description: o.description });
+      if (o.short) candidates.push({ value: o.short, description: o.description });
+    }
+    return { candidates, directive: Directive.Default };
+  }
+
+  // Case 3: subcommands available at this path → suggest them.
+  const subs = tables.subcommandsByPath.get(path) ?? [];
+  if (subs.length > 0) {
+    return {
+      candidates: subs.map((c) => ({ value: c.name, description: c.description })),
+      directive: Directive.Default,
+    };
+  }
+
+  // Case 4: positional value slot.
+  const positionals = tables.positionalsByPath.get(path) ?? [];
+  const idx = positionalIndex(tables, words, cword);
+  const pos =
+    positionals[idx] ??
+    (positionals[positionals.length - 1]?.variadic
+      ? positionals[positionals.length - 1]
+      : undefined);
+  if (pos) return valueCandidates(pos, cur, runProvider);
+
+  // Nothing structured to suggest → file completion.
+  return { candidates: [], directive: Directive.File };
+}
+
+/** Sentinel prefix for the trailing directive line in the wire protocol. */
+export const DIRECTIVE_PREFIX = "\x1f:";
+
+/**
+ * Serialize a result for the shell shim: one `value\tdescription` line per
+ * candidate, then a final `\x1f:<directive>` line. The \x1f (unit separator)
+ * prefix makes the directive line unambiguous against real candidate values.
+ */
+export function encodeResult(result: CompletionResult): string {
+  const lines = result.candidates.map((c) =>
+    c.description ? `${c.value}\t${c.description}` : c.value,
+  );
+  lines.push(`${DIRECTIVE_PREFIX}${result.directive}`);
+  return `${lines.join("\n")}\n`;
+}

package/src/lib/completion/zsh.ts

@@ -142,6 +142,40 @@ function truncate(s: string, n: number): string {
   return s.length > n ? `${s.slice(0, n - 1)}…` : s;
 }
 
+/**
+ * DYNAMIC zsh completion: a thin, tree-independent shim that calls
+ * `<bin> __complete-line` on every <Tab> (see bash.ts generateBashDynamic for
+ * the rationale). Candidate lines are `value\tdescription`; the shim converts
+ * the tab to `:` so `_describe` renders descriptions. The trailing `\x1f:<n>`
+ * line carries the directive (bit 0 = file fallback → `_files`).
+ */
+export function generateZshDynamic(binName: string): string {
+  const fn = fnPrefix(binName);
+  return `#compdef ${binName}
+# ${binName} zsh completion (dynamic; install once, never stale). Do not edit.
+${fn}() {
+  emulate -L zsh
+  local line directive=0
+  local -a raw display
+  raw=( "\${(@f)$(${binName} __complete-line $((CURRENT-1)) -- "\${words[@]}" 2>/dev/null)}" )
+  for line in $raw; do
+    [ -z "$line" ] && continue
+    if [[ "$line" == $'\\x1f:'* ]]; then
+      directive="\${line#$'\\x1f:'}"
+    else
+      display+=( "\${line//$'\\t'/:}" )
+    fi
+  done
+  if (( directive & 1 )); then
+    _files
+    return
+  fi
+  _describe -t values 'completions' display
+}
+compdef ${fn} ${binName}
+`;
+}
+
 /**
  * The driver walks `$words` to determine the current command path, then
  * dispatches to subcommand / option / value completion. `fn` is the

package/src/lib/docs-lint.ts

@@ -246,6 +246,11 @@ function checkNamingConvention(repoName: string, _repoPath: string, files: strin
     const name = basename(rel);
     // Allowlisted names
     if (ROOT_FILE_ALLOWLIST.has(name)) continue;
+    // Leading-underscore files are deliberate templates / meta files
+    // (e.g. _template.md), not content. The underscore is a convention
+    // marking "copy me, don't read me as a real doc", so exempt them
+    // from naming discipline rather than forcing kebab-case.
+    if (name.startsWith("_")) continue;
     // Dated files (audits/issues)
     if (DATED_FILE_PATTERN.test(name)) continue;
     // Changelogs