@indigoai-us/hq-cli 5.86.0 → 5.88.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [5.88.0]
+
+### Changed
+
+- Replaced the ten bundled `rebuild-*-index.sh` assets behind
+  `hq core rebuild-index <target>` with native, tested TypeScript renderers.
+  The command surface and scaffold-only assets remain unchanged, while rebuilds
+  no longer depend on bundled scaffold assets being present. (#311)
+
+## [5.87.0]
+
+### Added
+
+- Added the hidden `hq core worker` subgroup for worker-scoped skill
+  maintenance: `hq core worker lint` fails when a skill shared by multiple
+  workers is duplicated by copy instead of single-sourced (or a shared-skill
+  symlink dangles), and `hq core worker share` migrates duplicated copies onto
+  one canonical file plus relative symlinks (dry-run by default; refuses
+  cross-scope paths and never silently clobbers a drifted copy). (#309)
+- Added single-flight background reindex. (#308)
+
 ## [5.86.0]
 
 ### Added

package/assets/scaffold/core/scripts/lint-shared-worker-skills.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# lint-shared-worker-skills.sh — fail if a worker-scoped skill is duplicated by
+# copy instead of being single-sourced through the shared-skills convention.
+#
+# THE DRIFT PROBLEM this guards against: a skill used by several workers used to
+# be physically COPIED into each worker's skills/ directory. Editing one copy
+# left the others stale, so the copies drifted apart over time (e.g. a shared
+# e2e-testing skill splitting into two divergent versions). The fix is to keep
+# ONE canonical file under a scope-appropriate `_shared-skills/` store and point
+# each sharing worker's skill entry at it with a relative symlink — see
+# core/knowledge/public/hq-core/shared-worker-skills.md.
+#
+# This linter makes that convention enforceable. It flags two failure shapes:
+#
+#   DUPLICATE  — two or more NON-symlink skill files, in any worker under the
+#                scanned roots, whose byte content is identical. Identical bytes
+#                across two real files is exactly an un-single-sourced copy: the
+#                moment someone edits one, they drift. (Symlinks that resolve to
+#                a shared canonical are single-sourced and are NOT flagged, even
+#                though their resolved content matches the canonical.)
+#   BROKEN     — a skill entry that is a symlink whose target does not resolve.
+#
+# It deliberately does NOT flag two same-NAMED skills whose content differs
+# (e.g. an API-level vs a browser-level e2e skill): distinct content means they
+# are distinct skills that merely share a filename, not a drifted share.
+#
+# Usage: lint-shared-worker-skills.sh [root ...]
+#   Default roots: core/workers core/packages  (the SHIPPED hq-core scope —
+#   company `_shared-skills/` stores live under companies/<co>/ and are linted
+#   per-tenant, not here).
+#
+# Exit 0 + "OK:" line when clean; exit 1 + a report naming every offending group
+# when not. Matches the loud-and-specific style of lint-skill-script-refs.sh.
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$repo_root"
+
+roots=("$@")
+if [[ ${#roots[@]} -eq 0 ]]; then
+  roots=(core/workers core/packages)
+fi
+
+# Content hash of a file, portable across Linux and macOS (neither guaranteed to
+# ship the other's tool): md5sum (GNU) → md5 (BSD/macOS) → shasum (Perl, both).
+content_hash() {
+  if command -v md5sum >/dev/null 2>&1; then
+    md5sum "$1" | cut -d' ' -f1
+  elif command -v md5 >/dev/null 2>&1; then
+    md5 -q "$1"
+  else
+    shasum "$1" | cut -d' ' -f1
+  fi
+}
+
+# Collect skill entries: regular files AND symlinks named *.md under any
+# .../skills/... path. -type l must be matched explicitly — a symlink is not a
+# -type f, so a skills symlink would otherwise be invisible to the scan.
+mapfile -t entries < <(
+  find "${roots[@]}" \( -type f -o -type l \) -path '*/skills/*.md' 2>/dev/null | sort
+)
+
+# Empty is clean — and guards `"${entries[@]}"` under `set -u` on bash 3.2
+# (macOS), which errors on an empty array expansion.
+if [[ ${#entries[@]} -eq 0 ]]; then
+  echo "OK: worker-scoped skills are single-sourced (0 skill entries under: ${roots[*]})"
+  exit 0
+fi
+
+broken=()
+# Parallel arrays keyed by content hash: hash_keys[i] is a hash, and
+# hash_regfiles[i] is a newline-joined list of the NON-symlink files with that
+# hash. Bash 3.2 (macOS) has no associative arrays in a portable-guaranteed way,
+# so a linear scan over parallel arrays keeps this runnable everywhere HQ runs.
+hash_keys=()
+hash_regfiles=()
+
+hash_index() { # echo the index of $1 in hash_keys, or -1
+  local want="$1" i
+  for i in "${!hash_keys[@]}"; do
+    if [[ "${hash_keys[$i]}" == "$want" ]]; then
+      echo "$i"; return 0
+    fi
+  done
+  echo "-1"
+}
+
+for entry in "${entries[@]}"; do
+  if [[ -L "$entry" ]]; then
+    # Symlink: single-sourced by design. Only a DANGLING one is a problem.
+    if [[ ! -e "$entry" ]]; then
+      broken+=("$entry")
+    fi
+    continue
+  fi
+  # Regular file: hash its bytes and bucket it. Two regular files sharing a
+  # bucket are two copies of the same skill — the drift hazard.
+  h="$(content_hash "$entry")"
+  idx="$(hash_index "$h")"
+  if [[ "$idx" == "-1" ]]; then
+    hash_keys+=("$h")
+    hash_regfiles+=("$entry")
+  else
+    hash_regfiles[$idx]="${hash_regfiles[$idx]}"$'\n'"$entry"
+  fi
+done
+
+findings=0
+
+for i in "${!hash_keys[@]}"; do
+  group="${hash_regfiles[$i]}"
+  count="$(printf '%s\n' "$group" | grep -c .)"
+  if [[ "$count" -ge 2 ]]; then
+    if [[ $findings -eq 0 ]]; then
+      echo "lint-shared-worker-skills: FAIL — duplicated worker skills (single-source these via _shared-skills/ + relative symlinks):" >&2
+    fi
+    findings=$((findings + 1))
+    echo "  DUPLICATE (identical content, ${count} copies — pick one canonical and symlink the rest):" >&2
+    printf '    %s\n' "$group" >&2
+  fi
+done
+
+if [[ ${#broken[@]} -gt 0 ]]; then
+  if [[ $findings -eq 0 ]]; then
+    echo "lint-shared-worker-skills: FAIL — broken shared-skill symlink(s):" >&2
+  fi
+  findings=$((findings + ${#broken[@]}))
+  echo "  BROKEN (symlink target does not resolve):" >&2
+  printf '    %s\n' "${broken[@]}" >&2
+fi
+
+if [[ $findings -gt 0 ]]; then
+  echo "" >&2
+  echo "  Fix: keep ONE canonical file in the narrowest-scope _shared-skills/ store" >&2
+  echo "  (core/workers/_shared-skills, core/packages/<pack>/workers/_shared-skills," >&2
+  echo "  or companies/<co>/workers/_shared-skills) and replace each duplicate with a" >&2
+  echo "  relative symlink. Helper: hq core worker share" >&2
+  echo "  Doc: core/knowledge/public/hq-core/shared-worker-skills.md" >&2
+  exit 1
+fi
+
+echo "OK: worker-scoped skills are single-sourced (${#entries[@]} skill entries scanned under: ${roots[*]})"

package/assets/scaffold/core/scripts/share-worker-skill.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# share-worker-skill.sh — convert duplicated worker-scoped skill copies into a
+# single canonical file plus relative symlinks, the migration step for the
+# shared-worker-skills convention (core/knowledge/public/hq-core/shared-worker-skills.md).
+#
+# This performs the ONLY mechanical move the design needs: it never edits any
+# worker.yaml (the skill name still resolves to the same path — only the file
+# type changes from regular file to symlink), and it never touches a skill
+# resolver. `/run` reads {worker}/skills/{skill}.md and follows the symlink
+# transparently, so the change is purely file-layout.
+#
+# Usage:
+#   share-worker-skill.sh <scope-dir> <skill-name> <worker-skill-path> [<worker-skill-path> ...]
+#
+#   <scope-dir>          The narrowest scope that contains EVERY sharing worker,
+#                        e.g. core/workers, core/packages/<pack>/workers, or
+#                        companies/<co>/workers. The canonical file is created at
+#                        <scope-dir>/_shared-skills/<skill-name>.md.
+#   <skill-name>         Bare skill name (no .md), e.g. e2e-testing.
+#   <worker-skill-path>  Each worker's current copy, e.g.
+#                        core/workers/foo/skills/e2e-testing.md
+#
+# Safety rails:
+#   * Every worker path MUST live under <scope-dir> (no cross-scope symlinks,
+#     which would break on pack install / hq-sync). Refuses otherwise.
+#   * If no canonical exists yet, the FIRST worker path is promoted to canonical.
+#   * A worker copy whose content DIFFERS from the canonical is a DRIFTED copy:
+#     the script refuses and tells you to reconcile by hand first (the human
+#     decision the design reserves — never a silent overwrite). Re-run after
+#     reconciling, or pass --force to accept the canonical for that copy.
+#   * Idempotent: a path already symlinked to the canonical is left alone.
+#   * DRY-RUN BY DEFAULT. Pass --apply to make changes.
+
+set -euo pipefail
+
+APPLY=0
+FORCE=0
+args=()
+for a in "$@"; do
+  case "$a" in
+    --apply) APPLY=1 ;;
+    --force) FORCE=1 ;;
+    -*) echo "unknown flag: $a" >&2; exit 2 ;;
+    *) args+=("$a") ;;
+  esac
+done
+
+if [[ ${#args[@]} -lt 3 ]]; then
+  echo "usage: $0 [--apply] [--force] <scope-dir> <skill-name> <worker-skill-path>..." >&2
+  exit 2
+fi
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$repo_root"
+
+scope_dir="${args[0]%/}"
+skill_name="${args[1]}"
+worker_paths=("${args[@]:2}")
+
+if [[ ! "$skill_name" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]]; then
+  echo "error: skill-name '$skill_name' is not a bare skill name (no slashes, no .md)" >&2
+  exit 2
+fi
+if [[ ! -d "$scope_dir" ]]; then
+  echo "error: scope dir does not exist: $scope_dir" >&2
+  exit 2
+fi
+
+canonical="$scope_dir/_shared-skills/$skill_name.md"
+
+note() { printf '%s\n' "$*"; }
+would() { if [[ $APPLY -eq 1 ]]; then note "  did:   $*"; else note "  would: $*"; fi; }
+
+# Normalize a path to repo-relative without requiring GNU realpath (macOS-safe).
+rel_under() { # rel_under <path> <dir> → 0 if <path> is inside <dir>
+  local p="${1#./}" d="${2#./}"
+  [[ "$p" == "$d/"* ]]
+}
+
+# rel_path <from-dir> <to-file> → relative path from <from-dir> to <to-file>,
+# computed purely from the two repo-relative strings (both already normalized,
+# no `..` segments, no symlinks in the literal path). Portable: no python3, no
+# GNU realpath --relative-to (macOS ships neither).
+rel_path() {
+  local from="${1#./}" to="${2#./}"
+  local -a fa ta
+  IFS='/' read -r -a fa <<< "$from"
+  IFS='/' read -r -a ta <<< "$to"
+  local i=0
+  while [[ $i -lt ${#fa[@]} && $i -lt ${#ta[@]} && "${fa[$i]}" == "${ta[$i]}" ]]; do
+    i=$((i + 1))
+  done
+  local up="" j
+  for (( j=i; j<${#fa[@]}; j++ )); do up="../$up"; done
+  local down="" k
+  for (( k=i; k<${#ta[@]}; k++ )); do down="$down${ta[$k]}/"; done
+  down="${down%/}"
+  printf '%s%s' "$up" "$down"
+}
+
+# Every worker path must be inside the scope dir.
+for wp in "${worker_paths[@]}"; do
+  wp="${wp#./}"
+  if ! rel_under "$wp" "$scope_dir"; then
+    echo "error: worker path '$wp' is not under scope dir '$scope_dir'" >&2
+    echo "       canonical must live in the narrowest scope covering all sharers;" >&2
+    echo "       cross-scope symlinks are disallowed. Aborting (no changes made)." >&2
+    exit 2
+  fi
+done
+
+note "Canonical: $canonical"
+note "Scope:     $scope_dir"
+[[ $APPLY -eq 1 ]] || note "(dry run — pass --apply to make changes)"
+
+# 1) Establish the canonical file.
+if [[ -e "$canonical" && ! -L "$canonical" ]]; then
+  note "canonical already exists (regular file) — reusing it"
+else
+  # Promote the first worker path that is a real (non-symlink) file.
+  seed=""
+  for wp in "${worker_paths[@]}"; do
+    if [[ -f "$wp" && ! -L "$wp" ]]; then seed="$wp"; break; fi
+  done
+  if [[ -z "$seed" ]]; then
+    echo "error: no canonical exists and no worker path is a regular file to seed it from" >&2
+    exit 2
+  fi
+  would "mkdir -p $scope_dir/_shared-skills"
+  would "git mv $seed $canonical  (promote first copy to canonical)"
+  if [[ $APPLY -eq 1 ]]; then
+    mkdir -p "$scope_dir/_shared-skills"
+    git mv "$seed" "$canonical" 2>/dev/null || mv "$seed" "$canonical"
+  fi
+fi
+
+# 2) Point each worker path at the canonical via a relative symlink.
+for wp in "${worker_paths[@]}"; do
+  wp="${wp#./}"
+  # Already the canonical file itself (post-promotion) → link it too so every
+  # worker slot is a symlink and the canonical lives only under _shared-skills.
+  target_dir="$(dirname "$wp")"
+  # Relative path from the worker's skills dir to the canonical (portable).
+  rel="$(rel_path "$target_dir" "$canonical")"
+
+  if [[ -L "$wp" ]]; then
+    cur="$(readlink "$wp")"
+    if [[ "$cur" == "$rel" ]]; then
+      note "ok: $wp already links to canonical"
+      continue
+    fi
+    would "relink $wp -> $rel (was: $cur)"
+    if [[ $APPLY -eq 1 ]]; then ln -sfn "$rel" "$wp"; fi
+    continue
+  fi
+
+  if [[ -e "$wp" ]]; then
+    # Regular file present — must match canonical or be reconciled first.
+    if cmp -s "$wp" "$canonical"; then
+      would "replace identical copy $wp with symlink -> $rel"
+      if [[ $APPLY -eq 1 ]]; then rm -f "$wp"; ln -s "$rel" "$wp"; fi
+    else
+      if [[ $FORCE -eq 1 ]]; then
+        would "FORCE replace DRIFTED copy $wp with symlink -> $rel (content discarded)"
+        if [[ $APPLY -eq 1 ]]; then rm -f "$wp"; ln -s "$rel" "$wp"; fi
+      else
+        echo "  DRIFT: $wp differs from canonical — reconcile by hand, then re-run" >&2
+        echo "         (diff $wp $canonical), or pass --force to accept canonical." >&2
+        exit 3
+      fi
+    fi
+  else
+    would "create symlink $wp -> $rel"
+    if [[ $APPLY -eq 1 ]]; then mkdir -p "$target_dir"; ln -s "$rel" "$wp"; fi
+  fi
+done
+
+note "done."

package/dist/commands/core.d.ts

@@ -29,6 +29,7 @@
  * `ScaffoldRoot`.
  */
 import { Command } from "commander";
+import { type IndexTarget } from "../lib/index-render/index.js";
 /**
  * Which tree a scaffold script operates on, mirroring how the ORIGINAL script
  * found its root before it moved. Getting this wrong is not cosmetic: injecting a
@@ -64,14 +65,33 @@ export type ScaffoldCommand = ScaffoldAsset & {
     /** Direct subcommand name — `hq core <name>`. */
     name: string;
 };
-export type RebuildIndexTarget = ScaffoldAsset & {
+export type RebuildIndexTarget = {
     /** Rebuild target — `hq core rebuild-index <target>`. */
     target: string;
+    /** Native renderer identifier. */
+    renderer: IndexTarget;
+    /** One-line summary, shown in `hq core --help`. */
+    summary: string;
+};
+export type WorkerSubcommand = ScaffoldAsset & {
+    /** Subcommand name under the `worker` group — `hq core worker <name>`. */
+    name: string;
 };
+/**
+ * The `hq core worker <name>` subgroup — worker-scoped skill maintenance.
+ *
+ * Both are cold, explicitly-invoked operations (a linter and a one-shot
+ * migration), which the scaffold-vs-cli-code-ownership policy permits in the
+ * CLI. They are `root: "cwd"` because each derives its root from the caller
+ * (`git rev-parse --show-toplevel || pwd`): the CLI must inject nothing, or it
+ * would retarget the lint at the CLI's own checkout instead of the HQ tree the
+ * operator is standing in. See core/knowledge/public/hq-core/shared-worker-skills.md.
+ */
+export declare const WORKER_SUBCOMMANDS: WorkerSubcommand[];
 /**
  * The ten index rebuild targets. The command registration below intentionally
  * loops over this table for lookup, so adding a target never requires another
- * action handler and every target retains its own bundled asset.
+ * action handler and every target retains its own native renderer.
  */
 export declare const REBUILD_INDEX_TARGETS: RebuildIndexTarget[];
 /**
@@ -83,7 +103,13 @@ export declare const REBUILD_INDEX_TARGETS: RebuildIndexTarget[];
  * would make the forwarders harder to audit against this table.
  */
 export declare const SCAFFOLD_COMMANDS: ScaffoldCommand[];
-/** Every bundled asset, used by packaging and interpreter tests. */
+/**
+ * Bundled solely for HQ-root scaffolds, which still need these as loose files.
+ * `rebuild-index` dispatches them natively since this change, so none has a
+ * direct `hq core` command.
+ */
+export declare const SCAFFOLD_ONLY_ASSETS: ScaffoldAsset[];
+/** Every claimed bundled asset, used by packaging and interpreter tests. */
 export declare const SCAFFOLD_ASSETS: ScaffoldAsset[];
 export declare function registerCoreCommands(program: Command): Command;
 export {};

package/dist/commands/core.js

@@ -32,70 +32,85 @@ import { Option } from "commander";
 import { registerCoreCheckpointCommand } from "./core-checkpoint.js";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { runBundledScript } from "../utils/run-bundled-script.js";
+import { renderIndexTarget } from "../lib/index-render/index.js";
+/**
+ * The `hq core worker <name>` subgroup — worker-scoped skill maintenance.
+ *
+ * Both are cold, explicitly-invoked operations (a linter and a one-shot
+ * migration), which the scaffold-vs-cli-code-ownership policy permits in the
+ * CLI. They are `root: "cwd"` because each derives its root from the caller
+ * (`git rev-parse --show-toplevel || pwd`): the CLI must inject nothing, or it
+ * would retarget the lint at the CLI's own checkout instead of the HQ tree the
+ * operator is standing in. See core/knowledge/public/hq-core/shared-worker-skills.md.
+ */
+export const WORKER_SUBCOMMANDS = [
+    {
+        name: "lint",
+        asset: "core/scripts/lint-shared-worker-skills.sh",
+        root: "cwd",
+        summary: "Fail on worker-scoped skills duplicated by copy instead of single-sourced",
+    },
+    {
+        name: "share",
+        asset: "core/scripts/share-worker-skill.sh",
+        root: "cwd",
+        summary: "Migrate duplicated worker skills onto one canonical file + relative symlinks",
+    },
+];
 /**
  * The ten index rebuild targets. The command registration below intentionally
  * loops over this table for lookup, so adding a target never requires another
- * action handler and every target retains its own bundled asset.
+ * action handler and every target retains its own native renderer.
  */
 export const REBUILD_INDEX_TARGETS = [
     {
         target: "all",
-        asset: "core/scripts/rebuild-all-indexes.sh",
-        root: "live",
+        renderer: "all",
         summary: "Regenerate every INDEX.md across the HQ tree",
     },
     {
         target: "companies",
-        asset: "core/scripts/rebuild-companies-index.sh",
-        root: "live",
+        renderer: "companies",
         summary: "Regenerate companies/INDEX.md",
     },
     {
         target: "company-knowledge",
-        asset: "core/scripts/rebuild-company-knowledge-index.sh",
-        root: "live",
+        renderer: "company-knowledge",
         summary: "Regenerate a company's knowledge INDEX.md",
     },
     {
         target: "orchestrator",
-        asset: "core/scripts/rebuild-orchestrator-index.sh",
-        root: "live",
+        renderer: "orchestrator",
         summary: "Regenerate the orchestrator workspace INDEX.md",
     },
     {
         target: "projects",
-        asset: "core/scripts/rebuild-projects-index.sh",
-        root: "live",
+        renderer: "projects",
         summary: "Regenerate the projects INDEX.md",
     },
     {
         target: "public-knowledge",
-        asset: "core/scripts/rebuild-public-knowledge-index.sh",
-        root: "live",
+        renderer: "public-knowledge",
         summary: "Regenerate core/knowledge/public/INDEX.md",
     },
     {
         target: "reports",
-        asset: "core/scripts/rebuild-reports-index.sh",
-        root: "live",
+        renderer: "reports",
         summary: "Regenerate the reports INDEX.md",
     },
     {
         target: "social-drafts",
-        asset: "core/scripts/rebuild-social-drafts-index.sh",
-        root: "live",
+        renderer: "social-drafts",
         summary: "Regenerate workspace/social-drafts/INDEX.md",
     },
     {
         target: "threads",
-        asset: "core/scripts/rebuild-threads-index.sh",
-        root: "live",
+        renderer: "threads",
         summary: "Regenerate the session-threads INDEX.md",
     },
     {
         target: "workers",
-        asset: "core/scripts/rebuild-workers-index.sh",
-        root: "live",
+        renderer: "workers",
         summary: "Regenerate the workers INDEX.md",
     },
 ];
@@ -177,10 +192,68 @@ export const SCAFFOLD_COMMANDS = [
         summary: "Create a git worktree under workspace/worktrees/",
     },
 ];
-/** Every bundled asset, used by packaging and interpreter tests. */
+/**
+ * Bundled solely for HQ-root scaffolds, which still need these as loose files.
+ * `rebuild-index` dispatches them natively since this change, so none has a
+ * direct `hq core` command.
+ */
+export const SCAFFOLD_ONLY_ASSETS = [
+    {
+        asset: "core/scripts/rebuild-all-indexes.sh",
+        root: "cwd",
+        summary: "Scaffold-only native rebuild-index companion",
+    },
+    {
+        asset: "core/scripts/rebuild-companies-index.sh",
+        root: "cwd",
+        summary: "Scaffold-only native rebuild-index companion",
+    },
+    {
+        asset: "core/scripts/rebuild-company-knowledge-index.sh",
+        root: "cwd",
+        summary: "Scaffold-only native rebuild-index companion",
+    },
+    {
+        asset: "core/scripts/rebuild-orchestrator-index.sh",
+        root: "cwd",
+        summary: "Scaffold-only native rebuild-index companion",
+    },
+    {
+        asset: "core/scripts/rebuild-projects-index.sh",
+        root: "cwd",
+        summary: "Scaffold-only native rebuild-index companion",
+    },
+    {
+        asset: "core/scripts/rebuild-public-knowledge-index.sh",
+        root: "cwd",
+        summary: "Scaffold-only native rebuild-index companion",
+    },
+    {
+        asset: "core/scripts/rebuild-reports-index.sh",
+        root: "cwd",
+        summary: "Scaffold-only native rebuild-index companion",
+    },
+    {
+        asset: "core/scripts/rebuild-social-drafts-index.sh",
+        root: "cwd",
+        summary: "Scaffold-only native rebuild-index companion",
+    },
+    {
+        asset: "core/scripts/rebuild-threads-index.sh",
+        root: "cwd",
+        summary: "Scaffold-only native rebuild-index companion",
+    },
+    {
+        asset: "core/scripts/rebuild-workers-index.sh",
+        root: "cwd",
+        summary: "Scaffold-only native rebuild-index companion",
+    },
+];
+/** Every claimed bundled asset, used by packaging and interpreter tests. */
 export const SCAFFOLD_ASSETS = [
-    ...REBUILD_INDEX_TARGETS,
     ...SCAFFOLD_COMMANDS,
+    ...SCAFFOLD_ONLY_ASSETS,
+    ...WORKER_SUBCOMMANDS,
 ];
 /**
  * Resolve the tree an entry runs against, and the cwd to run it in.
@@ -237,6 +310,27 @@ export function registerCoreCommands(program) {
     // This group primarily hosts manifest-driven bundled assets, but it also
     // hosts native TypeScript plumbing when a scaffold contract needs it.
     registerCoreCheckpointCommand(core);
+    // `hq core worker <name>` — a nested subgroup for worker-scoped skill
+    // maintenance. Nested (rather than flat `hq core worker-<name>`) so the two
+    // related operations read as one family.
+    const worker = core
+        .command("worker")
+        .description("Worker-scoped skill maintenance (lint, share)");
+    for (const entry of WORKER_SUBCOMMANDS) {
+        worker
+            .command(entry.name)
+            .description(entry.summary)
+            // Pure passthrough: the wrapped script owns its own argument grammar.
+            .allowUnknownOption()
+            .allowExcessArguments()
+            .helpOption(false)
+            .argument("[args...]", "arguments passed through to the script")
+            .action((args = [], _opts, cmd) => {
+            const scope = core.opts();
+            const operands = cmd.args.length > 0 ? cmd.args : args;
+            runEntry(entry, scope, operands);
+        });
+    }
     const runCommand = (entry, args = [], cmd, target) => {
         const scope = core.opts();
         // `cmd.args` is the authoritative operand list: with
@@ -261,7 +355,10 @@ export function registerCoreCommands(program) {
         if (!entry) {
             throw expectedUserError(`Unknown rebuild-index target "${target}". Valid targets: ${validTargets.join(", ")}.`);
         }
-        runCommand(entry, args, cmd, target);
+        const scope = core.opts();
+        const hqRoot = resolveLiveRoot({ hqRoot: scope.hqRoot });
+        const operands = cmd.args.length > 0 ? cmd.args : args;
+        renderIndexTarget(entry.renderer, { root: hqRoot, log: (message) => process.stderr.write(`${message}\n`) }, operands.slice(1));
     });
     for (const entry of SCAFFOLD_COMMANDS) {
         core

package/dist/commands/index-cmd.d.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import { type RunQmdOptions, type SearchCollection, type QmdProcessResult } from '../lib/search-index/index.js';
+import { type BackgroundDependencies, type BackgroundResult, type BackgroundStatus } from '../lib/search-index/background.js';
 export type SearchIndexDependencies = {
     reconcileCollections: (hqRoot: string) => unknown;
     deriveCollections: (hqRoot: string) => SearchCollection[];
@@ -7,6 +8,9 @@ export type SearchIndexDependencies = {
     resolveQmdBin: () => string;
     resolveQmdVersion: () => string | undefined;
     runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
+    runBackgroundLauncher?: (dependencies: BackgroundDependencies) => BackgroundResult;
+    runBackgroundWorker?: (dependencies: BackgroundDependencies) => BackgroundResult;
+    backgroundStatus?: (dependencies: BackgroundDependencies) => BackgroundStatus;
 };
 /** Incrementally update qmd, embedding only when an operator explicitly asks. */
 export declare function syncSearchIndex(hqRoot: string, embed: boolean, dependencies?: SearchIndexDependencies): void;