@indigoai-us/hq-cli 5.196.0 → 5.198.0

package/dist/command-catalog.generated.js

@@ -8840,6 +8840,512 @@ export const COMMAND_CATALOG = [
         "arguments": [],
         "options": [],
         "subcommands": [
+            {
+                "name": "blocker",
+                "description": "Record and manage project blockers",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "open",
+                        "description": "Open a blocker",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--story <id>",
+                                "description": "Blocked story id"
+                            },
+                            {
+                                "flags": "--what <text>",
+                                "description": "What is blocked"
+                            },
+                            {
+                                "flags": "--waiting-on <text>",
+                                "description": "Who or what is needed"
+                            },
+                            {
+                                "flags": "--next-step <text>",
+                                "description": "Next action"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "update",
+                        "description": "Update a blocker",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <blocker-id>",
+                        "arguments": [
+                            {
+                                "name": "blocker-id",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--waiting-on <text>",
+                                "description": "Who or what is needed"
+                            },
+                            {
+                                "flags": "--next-step <text>",
+                                "description": "Next action"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "resolve",
+                        "description": "Resolve a blocker",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <blocker-id>",
+                        "arguments": [
+                            {
+                                "name": "blocker-id",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--resolution <text>",
+                                "description": "Resolution details"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "list",
+                        "description": "List blockers",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--all",
+                                "description": "Include resolved blockers"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    }
+                ]
+            },
+            {
+                "name": "kpi",
+                "description": "Define KPIs and record values",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "define",
+                        "description": "Define a proposed KPI",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--name <text>",
+                                "description": "KPI name"
+                            },
+                            {
+                                "flags": "--definition <text>",
+                                "description": "Definition or query"
+                            },
+                            {
+                                "flags": "--unit <unit>",
+                                "description": "Measurement unit"
+                            },
+                            {
+                                "flags": "--target <number>",
+                                "description": "Target value"
+                            },
+                            {
+                                "flags": "--direction <direction>",
+                                "description": "up | down"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "record",
+                        "description": "Record a KPI value",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <kpi-id>",
+                        "arguments": [
+                            {
+                                "name": "kpi-id",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--value <number>",
+                                "description": "Observed value"
+                            },
+                            {
+                                "flags": "--source <text>",
+                                "description": "Value source"
+                            },
+                            {
+                                "flags": "--at <iso>",
+                                "description": "Observation time"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "approve",
+                        "description": "Approve a KPI proposal",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <kpi-id>",
+                        "arguments": [
+                            {
+                                "name": "kpi-id",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "list",
+                        "description": "List KPIs",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    }
+                ]
+            },
+            {
+                "name": "okr",
+                "description": "Set and approve OKRs",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "set",
+                        "description": "Create a proposed OKR",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--objective <text>",
+                                "description": "Objective"
+                            },
+                            {
+                                "flags": "--period <period>",
+                                "description": "Planning period"
+                            },
+                            {
+                                "flags": "--key-result <text=kpi-id:target>",
+                                "description": "Key result"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "approve",
+                        "description": "Approve an OKR proposal",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <okr-id>",
+                        "arguments": [
+                            {
+                                "name": "okr-id",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "list",
+                        "description": "List OKRs",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    }
+                ]
+            },
+            {
+                "name": "directive",
+                "description": "Record directives and acknowledgements",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "record",
+                        "description": "Record a directive",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--text <text>",
+                                "description": "Verbatim directive"
+                            },
+                            {
+                                "flags": "--date <yyyy-mm-dd>",
+                                "description": "Directive date"
+                            },
+                            {
+                                "flags": "--source-url <url>",
+                                "description": "Source URL"
+                            },
+                            {
+                                "flags": "--team <slug>",
+                                "description": "Affected team (repeatable)"
+                            },
+                            {
+                                "flags": "--policy-path <path>",
+                                "description": "Related policy path"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "ack",
+                        "description": "Acknowledge a directive",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <directive-id>",
+                        "arguments": [
+                            {
+                                "name": "directive-id",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--team <slug>",
+                                "description": "Acknowledging team"
+                            },
+                            {
+                                "flags": "--lane <lane-id>",
+                                "description": "Acknowledging lane id"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "list",
+                        "description": "List directives",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--project <slug>",
+                                "description": "HQ team project slug"
+                            },
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Select the company by slug"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    }
+                ]
+            },
             {
                 "name": "outpost-pruner",
                 "description": "Inspect, install, and run safe outpost worktree pruning",

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

@@ -15,14 +15,20 @@ export type SearchIndexDependencies = {
     runBackgroundLauncher?: (dependencies: BackgroundDependencies) => BackgroundResult;
     runBackgroundWorker?: (dependencies: BackgroundDependencies) => BackgroundResult | Promise<BackgroundResult>;
     backgroundStatus?: (dependencies: BackgroundDependencies) => BackgroundStatus;
-    /** Test seams for the lock shared by every hq-cli embed entry point. */
+    /** Test seams for the lock shared by every hq-cli QMD writer. */
     embedLockDependencies?: EmbedLockDependencies;
+    /** Test seam for the default-off shared lock around the full reindex pass. */
+    singleFlightEnabled?: () => boolean;
     /** Test seams for the host load gate consulted while the embed lock is held. */
     loadGateDependencies?: LoadGateDependencies;
     writeStderr?: (text: string) => void;
 };
 export type SyncSearchIndexResult = {
+    status: 'updated';
     embedded: boolean;
+} | {
+    status: 'skipped';
+    reason: 'busy' | 'unavailable';
 };
 /** Incrementally update qmd, embedding only when an operator explicitly asks. */
 export declare function syncSearchIndex(hqRoot: string, embed: boolean, dependencies?: SearchIndexDependencies): SyncSearchIndexResult;

package/dist/commands/index-cmd.js

@@ -4,6 +4,7 @@ import { backgroundStatus, defaultBackgroundDependencies, runBackgroundLauncher,
 import { defaultEmbedLockDependencies, runWithEmbedLock, } from '../lib/search-index/embed-lock.js';
 import { checkEmbedLoad, defaultLoadGateDependencies, recordSuccessfulEmbed, } from '../lib/search-index/load-gate.js';
 import { applyIndexSizeLimit } from '../lib/search-index/max-doc-bytes.js';
+import { qmdReindexSingleFlightEnabled } from '../lib/search-index/reindex-single-flight-flag.js';
 import { findHqRoot } from '../utils/manifest.js';
 import { QMD_NATIVE_BINDING_REMEDY, isQmdNativeBindingError, } from '../utils/qmd-native-binding-error.js';
 import { isQmdStoreMissingError, qmdStoreMissingMessage, } from '../utils/qmd-store-missing-error.js';
@@ -23,27 +24,29 @@ const defaults = {
 };
 /** Incrementally update qmd, embedding only when an operator explicitly asks. */
 export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
-    dependencies.reconcileCollections(hqRoot);
-    // Must precede the update: an oversized file is skipped at glob time or not
-    // at all, so capping after the update would still have paid to read it.
-    //
-    // Best-effort, matching the background worker. The cap writes to qmd's config
-    // and to `.hq/`, either of which can be read-only on a locked-down box. An
-    // index that is merely uncapped is far better than no `qmd update` at all.
-    try {
-        dependencies.applyIndexSizeLimit(hqRoot);
-    }
-    catch {
-        /* capping is an optimisation; indexing is the job */
-    }
-    dependencies.runQmd(['update'], { cwd: hqRoot });
-    if (!embed)
-        return { embedded: false };
-    const lockDependencies = dependencies.embedLockDependencies ?? defaultEmbedLockDependencies();
+    const updateIndex = () => {
+        dependencies.reconcileCollections(hqRoot);
+        // Must precede the update: an oversized file is skipped at glob time or not
+        // at all, so capping after the update would still have paid to read it.
+        //
+        // Best-effort, matching the background worker. The cap writes to qmd's config
+        // and to `.hq/`, either of which can be read-only on a locked-down box. An
+        // index that is merely uncapped is far better than no `qmd update` at all.
+        try {
+            dependencies.applyIndexSizeLimit(hqRoot);
+        }
+        catch {
+            /* capping is an optimisation; indexing is the job */
+        }
+        dependencies.runQmd(['update'], { cwd: hqRoot });
+    };
     const writeStderr = dependencies.writeStderr ?? ((text) => process.stderr.write(text));
+    const singleFlightEnabled = (dependencies.singleFlightEnabled ?? qmdReindexSingleFlightEnabled)();
+    const lockDependencies = dependencies.embedLockDependencies ?? defaultEmbedLockDependencies();
     const home = resolveQmdHome(lockDependencies.env);
-    const loadGateDependencies = dependencies.loadGateDependencies ?? defaultLoadGateDependencies(lockDependencies.env);
-    const outcome = runWithEmbedLock(home, lockDependencies, () => {
+    let embedded = false;
+    const runEmbed = () => {
+        const loadGateDependencies = dependencies.loadGateDependencies ?? defaultLoadGateDependencies(lockDependencies.env);
         const decision = checkEmbedLoad(home, loadGateDependencies);
         if (decision.action === 'skip') {
             writeStderr(decision.notice);
@@ -53,13 +56,33 @@ export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
             writeStderr(decision.notice);
         dependencies.runQmd(['embed'], { cwd: hqRoot });
         recordSuccessfulEmbed(home, loadGateDependencies);
+        embedded = true;
         return undefined;
-    });
+    };
+    if (singleFlightEnabled) {
+        const outcome = runWithEmbedLock(home, lockDependencies, () => {
+            updateIndex();
+            return embed ? runEmbed() : undefined;
+        });
+        if (outcome === 'busy') {
+            writeStderr('hq: qmd reindex is already running; skipping this pass.\n');
+            return { status: 'skipped', reason: 'busy' };
+        }
+        if (outcome === 'unavailable') {
+            writeStderr('hq: cannot access the qmd reindex lock; skipping this pass.\n');
+            return { status: 'skipped', reason: 'unavailable' };
+        }
+        return { status: 'updated', embedded };
+    }
+    updateIndex();
+    if (!embed)
+        return { status: 'updated', embedded: false };
+    const outcome = runWithEmbedLock(home, lockDependencies, runEmbed);
     if (outcome === 'busy')
         writeStderr('hq: qmd embed is already running; skipping this pass.\n');
     if (outcome === 'unavailable')
         writeStderr('hq: cannot access the qmd embed lock; skipping this pass.\n');
-    return { embedded: outcome === 'ran' };
+    return { status: 'updated', embedded: outcome === 'ran' && embedded };
 }
 function resolveRoot(hqRoot) {
     return hqRoot ?? findHqRoot();
@@ -97,6 +120,8 @@ export function registerIndexCommand(program, dependencies = defaults) {
         .action((options) => {
         const hqRoot = resolveRoot(options.hqRoot);
         const result = syncSearchIndex(hqRoot, options.embed === true, dependencies);
+        if (result.status === 'skipped')
+            return;
         console.log(`Updated search index for ${hqRoot}${result.embedded ? ' (including embeddings)' : ''}.`);
     });
     index

package/dist/commands/lanes-tracker.d.ts

@@ -0,0 +1,20 @@
+import type { Command } from "commander";
+import { type TrackerStore } from "../lib/lanes/tracker-store.js";
+import type { LaneCompanyRef } from "../lib/lanes/types.js";
+export declare const LANES_TRACKER_FLAG = "lanes.tracker";
+export declare const LANES_TRACKER_MESH_FLAG = "lanes.tracker-mesh";
+export interface LaneTrackerCommandDeps {
+    hqRoot: () => string;
+    resolveCompany: (company?: string) => Promise<LaneCompanyRef>;
+    trackerEnabled: (company: LaneCompanyRef) => boolean | Promise<boolean>;
+    trackerMeshEnabled: (company: LaneCompanyRef) => boolean | Promise<boolean>;
+    now: () => Date;
+    actor: () => string | null;
+    /** Test seam; production uses the same local store used by the public commands. */
+    store?: (projectDirectory: string) => TrackerStore;
+}
+type WrapHandler = <Args extends unknown[]>(action: (...args: Args) => Promise<void>) => (...args: Args) => Promise<void>;
+export declare function registerLaneTrackerCommands(parent: Command, deps: LaneTrackerCommandDeps, wrap: WrapHandler): void;
+export declare function defaultTrackerActor(): string | null;
+export {};
+//# sourceMappingURL=lanes-tracker.d.ts.map