@indigoai-us/hq-cli 5.345.118 → 5.345.119

package/dist/commands/core-pipeline-conductor-command.js

@@ -0,0 +1,138 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveLiveRoot } from "../utils/hq-roots.js";
+import { runBundledScript } from "../utils/run-bundled-script.js";
+import { describeCoreCommand } from "./core-command-catalog.js";
+import { coreNativePipelineEnabled } from "./core-native-pipeline-flag.js";
+export const PIPELINE_CONDUCTOR_ASSET = "core/scripts/pipeline-conductor.sh";
+export const PIPELINE_DRIVER_ASSET = "core/scripts/pipeline-driver.sh";
+const CONDUCTOR_USAGE = "# pipeline-conductor.sh - deterministic helpers for the pipeline-conductor\n# worker (/run-project --pipeline). The conductor owns a story queue and routes\n# each phase of each story to an hq-cli loop lane. It never spawns a child\n# agent: every phase runs in a lane the loop controller owns.\n#\n# Usage (every subcommand takes --state <dir>; most take --prd <prd.json>):\n#   next     --prd P --state S [--limit N]       eligible story ids, one per line\n#   classify --prd P --state S --story ID [--worktree DIR | --worktree REPO=DIR ...]\n#            [--overlay F] [--table T]           write stories/<id>.json (phases, repo,\n#                                                 worktree, classified_by); print phases\n#   classify --prd P --state S [--overlay F] [--table T]\n#                                                 (no --story) check every story that is not\n#                                                 passing or skipped, write nothing; prints\n#                                                 OK/WARN/ERROR lines, exit 1 on any ERROR\n#   overlay  set --state S --story ID --sequence a,b,c | overlay show --state S\n#                                                 the run's classification overlay\n#                                                 (<state>/overlay.json); the prd is not edited\n#   skip     --state S --story ID [--note TEXT] [--force] [--prd P]\n#   unskip   --state S --story ID               leave a story out of the run (skips.json)\n#   worktree --state S --repo R --shared [--prd P] [--story ID] [--story-branches]\n#            [--worktree DIR | --worktree R=DIR] [--allow-repos-worktree]\n#                                                 cut the run's worktree for repo R: one per\n#                                                 repo on the run's feature branch (default),\n#                                                 or one per story with --story-branches.\n#                                                 Default target, every mode:\n#                                                 <HQ>/workspace/worktrees/<project>/<repo-name>/\n#                                                 (<repo-name>-<story> with --story-branches)\n#   worktree --state S --repo R [--prd P]        without --shared: with --prd, the same cut\n#                                                 at the default target; without it, the repo\n#                                                 itself (refused under repos/, see below)\n#   route    --prd P --state S --story ID         queue the story's current phase\n#   accept   --state S --story ID --handoff F     record a phase handoff and advance\n#   recheck  --prd P --state S --story ID         re-read literal ACs against ac_evidence\n#   gate     tick|status --state S\n#   gate     result --state S pass|fail [--note TEXT]\n#   release  --state S (--story ID [--worker W] | --worker W)\n#                                                 resolve an approval decision item\n#   report   story --state S --story ID | report final --state S\n#   tick     --prd P --state S [--worktree DIR | --worktree REPO=DIR ...] [--story-branches]\n#            [--table T]                         (the confirmed worker table; recorded in run.json)\n#                                                 one routing pass over the queue\n#   go       --state S --story ID [--note TEXT]   release a story held awaiting_go\n#   interrupt --state S [--story ID] [--note TEXT] mark every (or one) in_flight story interrupted (phase,\n#                                                 time) and withdraw its envelope from the lane\n#                                                 queue when no lane picked it up; prints\n#                                                 INTERRUPTED <id> <phase> withdrawn|picked_up\n#   stop     --state S [--note TEXT]              ask the run's driver to stop (driver/stop.json);\n#                                                 with no live driver, runs interrupt itself\n#\n# Run worktrees under repos/: the core Write/Edit guard blocks editor-tool writes\n#   under <HQ>/repos/, so a lane that edits with Write or Edit stalls there. An\n#   explicit --worktree (any command) that resolves under repos/ is refused\n#   (exit 2) unless --allow-repos-worktree is passed; with it, every phase\n#   envelope routed into that tree carries one constraint line telling the worker\n#   to edit through the shell or apply_patch. A worktree must still sit inside\n#   the HQ root for lanes to cd into it.\n#\n# Owner resolutions (the parent runs these after the owner answers; the\n# conductor and the driver never apply one on their own):\n#   resolve  --state S --story ID --as accepted-partial --note TEXT [--prd P]\n#                                                 accept a blocked story as a partial\n#                                                 draft; dependents may route; passes\n#                                                 is never set for it\n#   resolve  --state S --story ID --as retry [--note TEXT] [--prd P]\n#                                                 route the blocked phase again as a\n#                                                 fresh call; the note reaches the worker;\n#                                                 re-reads the story's phases from the prd\n#                                                 (P, else the prd run.json records), resumes\n#                                                 at the first phase without a passed handoff,\n#                                                 and starts the failed-attempt count over\n#   failcap  --state S --story ID                 the current phase returned failed too often:\n#                                                 hold the story as blocked_needs_owner and write\n#                                                 decisions/<id>-blocked-<phase>.md with each\n#                                                 failed handoff's text (exit 10)\n#   park     --state S --story ID [--note TEXT] [--prd P] [--force]\n#                                                 set the story aside; every story that\n#                                                 depends on it is held as parked_dependency.\n#                                                 Prints PARK_CLOSURE <id> <n>: <ids> first; more\n#                                                 than PC_PARK_CONFIRM (default 5) dependents\n#                                                 needs --force\n#   unpark   --state S --story ID [--prd P]       reverse park; prints UNPARK_RELEASES <id> <n>: <ids>\n# park, unpark, skip and unskip each append a line to <state>/decisions.log.\n#   reopen   --state S --story ID --note TEXT [--from-phase PHASE] [--prd P]\n#                                                 send a verified or accepted_partial story\n#                                                 back: queued at PHASE (default: the first\n#                                                 phase whose worker is not a reviewer or\n#                                                 tester), handoffs from PHASE on archived as\n#                                                 handoffs/<id>-<phase>.reopened.<n>.json, the\n#                                                 attempt count starts over, the note reaches\n#                                                 the worker in the envelope. Clears passes:true\n#                                                 in the prd. Verified dependents are not\n#                                                 reopened; the final summary lists them.\n#   gate     result --state S fail --story ID --note TEXT [--from-phase PHASE] [--prd P]\n#                                                 record a failed gate that names the story that\n#                                                 caused it: reopen that story (as above) and set\n#                                                 the gate to `reopened`, so routing goes on and\n#                                                 the reopened story routes first; the gate is due\n#                                                 again once every reopened story verifies\n# Each refuses a story in a state it does not apply to (exit 1) and is\n# idempotent: repeating it prints ALREADY and exits 0.\n#\n# State dir layout:\n#   stories/<id>.json        phases, current index, state, reroutes, worktree\n#   envelopes/<id>-<phase>.json   envelopes queued to hq lanes\n#   handoffs/<id>-<phase>.json    accepted phase handoffs\n#   decisions/<id>-<worker>.md    approval items for the parent session\n#   decisions/<id>-blocked-<phase>.md  a worker returned status blocked\n#   run.json                 the prd path the last tick used (for park and report)\n#   approvals.json           workers released for the whole run / per story\n#   gate.json                regression gate cadence and state\n#   report.md                one line per finished story + one final summary\n#\n# Classification (classify, and tick when a story first starts): the story's worker\n#   sequence is its full phase sequence, in order: the overlay entry, else\n#   worker_preference, else the keyword fallback (classified_by records which).\n#   classify refuses (exit 1, every problem listed) when:\n#   - a worker id has no worker.yaml under PC_WORKERS_ROOT (the message names the\n#     roots and the nearest known ids);\n#   - a story that declares code files (anything but docs/, markdown, text, yaml)\n#     starts with a verifier or reader (is_implementer below reads worker.role,\n#     else worker.type, from worker.yaml); prepend an implementer or set\n#     \"docs_only\": true;\n#   - a run with a worker table (--table, recorded by tick in run.json) has a\n#     sequence worker with no row in it.\n#   It warns (stderr, once per story) on a one-worker sequence, on a model_hint\n#   (a table pin wins: \"hint ignored, table pins <model>\"; a bare alias opus,\n#   sonnet, haiku or fable is never used), and on the dependency lint (dep_lint).\n#   route prints NO_LANE <id> <phase> <worker> and exits 12 when the current\n#   phase's worker has no table row; the story stays queued.\n#\n# Skip list: a skipped story (<state>/skips.json, stories/<id>.json state skipped)\n#   is not selected, routed, gated or counted; FINAL lists it with its note.\n#   Skipping a story others depend on prints SKIP_STRANDS and needs --force.\n#\n# Repo per story: classify resolves each story's repo, in this order:\n#   1. the story's `repoPath`;\n#   2. when the prd lists more than one repo, the repo that owns the story's first\n#      declared file (`files[0]`): an absolute path under the repo, a path from\n#      the HQ root, a path that starts with the repo's directory name, or a path\n#      that exists inside exactly one repo. The repo list is `metadata.repos[]`\n#      (canonical; each entry a path string or an object with `path` or\n#      `repoPath`); `metadata.repoPaths[]` (path strings) is read as an alias;\n#   3. `metadata.repoPath`.\n#   Relative repo paths are read from the HQ root. stories/<id>.json records\n#   the resolved `repo`. `tick --worktree <repo>=<worktree>` (repeatable) maps\n#   each repo to its worktree and every phase of a story goes to the worktree of\n#   its repo; the bare `--worktree <dir>` form serves a prd with at most one\n#   repo. A story whose repo has no worktree is held blocked_needs_owner with a\n#   decision item naming the repo; it is never routed to another repo's tree.\n#   The envelope carries `repo`, `worktree` and, for a git worktree, `branch`.\n#\n# Branches: `metadata.baseBranch` (default main) is the base. Every cut starts\n#   from origin/<baseBranch> when that ref exists after `git fetch origin\n#   <baseBranch>`, else from local <baseBranch>, never from the repo's HEAD; the\n#   exact ref is printed (CUT <branch> from <ref> <sha>). Neither ref: exit 1.\n#   Default mode: one feature branch per repo for the run (`metadata.branchName`,\n#   else feature/<project>) in one worktree per repo; every story of that repo\n#   commits on it in dependency order, one story in flight per repo branch.\n#   `--story-branches` (tick and worktree): one branch and worktree per story\n#   (pipeline/<id>), cut when the story first routes from the branch of the last\n#   verified story it depends on in the same repo (stacked), else from the base.\n#   A story whose dependency branch is missing is held blocked_needs_owner.\n#\n# Concurrency: in the default mode PC_MAX_STORIES is lowered to the number of\n#   worktrees in play (one story per repo branch at a time) and tick prints\n#   MAX_STORIES <n> with the reason when it lowers it.\n#\n# Story-level go: a story with `approval: \"explicit\"` (canonical; the alias\n#   `needsApproval: true` is read too), or one the release detector flags (its\n#   declared files or acceptance criteria mention deploy, release, production,\n#   or merging to the base branch; patterns in RELEASE_PATTERNS below), is held\n#   awaiting_go before its first implementing phase, whatever the worker's\n#   approval_required says, with decisions/<id>-go.md. Only `go` releases it;\n#   `release --worker` (whole-run approval) does not. resolve and park apply.\n#\n# Story states: queued, in_flight, held, awaiting_go, awaiting_recheck, verified, failed_report,\n#   blocked_needs_owner (a phase handoff said blocked; never retried on its own),\n#   accepted_partial (owner accepted a blocked story as a partial draft; counts as\n#   done for dependsOn, passes is never set), parked (owner set it aside),\n#   parked_dependency (depends, directly or not, on a parked story).\n# A reopened story is queued again with a `reopen` record (note, phase, the\n#   verified dependents at the time); report.md drops its earlier line.\n#\n# Back-pressure hint: when a story's `files` include a data store or schema path\n#   (contains store, schema, migration or db/), every envelope of that story\n#   carries a constraint asking the worker to run the repo's schema-contract\n#   tests, if present.\n#\n# A handoff with status `failed` re-queues the phase (the driver allows one\n# route-back). A handoff with status `blocked` holds the story as\n# blocked_needs_owner and writes one decision item: a rerun cannot help.\n# A state dir from the previous version (a queued story whose newest archived\n# handoff, handoffs/<id>-<phase>.failed.<n>.json, says blocked) is read as\n# blocked_needs_owner, so resolve works on it without hand edits.\n#\n# Exit codes: 0 ok; 1 refused or failed; 2 usage; 3 lane capacity/admission (retry next tick);\n#   10 held for a parent decision (approval hold, or a blocked handoff on accept);\n#   11 lane down: `hq lanes enqueue` returned `loop_not_running` or a terminal\n#      lane state. The worker mapping is dropped, the story stays queued, and\n#      route prints LANE_DOWN <id> <phase> <worker> ...; tick stops there.\n#   12 no lane: the phase's worker has no row in the run's worker table (NO_LANE);\n#      tick stops there.\n#\n# Env: PC_HQ (default hq), PC_ENVELOPE (default\n#   core/scripts/pipeline-envelope.sh), PC_WORKERS_ROOT (colon-separated worker\n#   roots, default below), PC_GATE_EVERY (default 3,\n#   the /run-project regression cadence), PC_NOW (epoch seconds, for tests),\n#   PC_DEADLINE_MIN (default 120), PC_MAX_STORIES (default 3), PC_HQ_ROOT,\n#   PC_PARK_CONFIRM (default 5). PC_WORKERS_ROOT defaults to core/workers, every\n#   companies/*/workers and personal/workers.\n#\n# The conductor never writes `passes` into prd.json. A verified story is\n# reported; the parent session decides what to record.\n#\n# bash 3.2 portable; JSON and YAML work is done by node.\n";
+const valueArgs = {
+    "--prd": "PC_PRD", "--state": "PC_STATE", "--story": "PC_STORY", "--handoff": "PC_HANDOFF",
+    "--repo": "PC_REPO", "--worker": "PC_WORKER", "--worktree": "PC_WT", "--limit": "PC_LIMIT",
+    "--note": "PC_NOTE", "--as": "PC_AS", "--from-phase": "PC_FROM_PHASE", "--overlay": "PC_OVERLAY",
+    "--table": "PC_TABLE", "--sequence": "PC_SEQUENCE",
+};
+function parseConductorArgs(args) {
+    if (!args.length || args[0] === "-h" || args[0] === "--help")
+        return { error: "", usage: true };
+    const command = args[0] ?? "";
+    let index = 1;
+    let subcommand = "";
+    if (["gate", "report", "overlay"].includes(command)) {
+        if (index >= args.length)
+            return { error: "", usage: true };
+        subcommand = args[index++] ?? "";
+    }
+    const values = {
+        PC_CMD: command, PC_SUB: subcommand, PC_PRD: "", PC_STATE: "", PC_STORY: "", PC_HANDOFF: "",
+        PC_WORKER: "", PC_WT: "", PC_LIMIT: "", PC_NOTE: "", PC_RESULT: "", PC_AS: "", PC_NOTE_SET: "0",
+        PC_FROM_PHASE: "", PC_REPO: "", PC_SHARED: "0", PC_STORY_BRANCHES: "0", PC_OVERLAY: "", PC_TABLE: "",
+        PC_SEQUENCE: "", PC_FORCE: "0", PC_ALLOW_REPOS: "0",
+    };
+    while (index < args.length) {
+        const arg = args[index] ?? "";
+        const envName = valueArgs[arg];
+        if (envName) {
+            if (index + 1 >= args.length)
+                return { error: "pipeline-conductor: " + arg + " needs a value" };
+            const value = args[index + 1] ?? "";
+            values[envName] = envName === "PC_WT" && values.PC_WT ? values.PC_WT + "\n" + value : value;
+            if (arg === "--note")
+                values.PC_NOTE_SET = "1";
+            index += 2;
+            continue;
+        }
+        if (arg === "--shared")
+            values.PC_SHARED = "1";
+        else if (arg === "--story-branches")
+            values.PC_STORY_BRANCHES = "1";
+        else if (arg === "--force")
+            values.PC_FORCE = "1";
+        else if (arg === "--allow-repos-worktree")
+            values.PC_ALLOW_REPOS = "1";
+        else if (arg === "pass" || arg === "fail")
+            values.PC_RESULT = arg;
+        else
+            return { error: "pipeline-conductor: unknown argument: " + arg };
+        index += 1;
+    }
+    if (!values.PC_STATE)
+        return { error: "pipeline-conductor: --state <dir> is required" };
+    if (values.PC_STORY.includes("/") || values.PC_STORY.includes("\\") || values.PC_STORY.startsWith("."))
+        return { error: "pipeline-conductor: unsafe story id: " + values.PC_STORY };
+    if (values.PC_LIMIT && Array.from(values.PC_LIMIT).some((ch) => ch < "0" || ch > "9"))
+        return { error: "pipeline-conductor: --limit must be a non-negative integer" };
+    return { values };
+}
+function prepareNativeEnvironment(values, root, cwd) {
+    const env = process.env;
+    env.PC_SELF_DIR = path.join(root, "core", "scripts");
+    env.PC_HQ_ROOT = root;
+    env.PC_HQ = env.PC_HQ || "hq";
+    env.PC_ENVELOPE = env.PC_ENVELOPE || path.join(root, "core", "scripts", "pipeline-envelope.sh");
+    if (!env.PC_WORKERS_ROOT) {
+        let roots = path.join(env.PC_HQ_ROOT, "core", "workers");
+        const companyRoot = path.join(env.PC_HQ_ROOT, "companies");
+        try {
+            for (const company of fs.readdirSync(companyRoot).sort()) {
+                const workers = path.join(companyRoot, company, "workers");
+                if (fs.existsSync(workers) && fs.statSync(workers).isDirectory())
+                    roots += ":" + workers;
+            }
+        }
+        catch { /* The original unmatched shell glob appends no company roots. */ }
+        roots += ":" + path.join(env.PC_HQ_ROOT, "personal", "workers");
+        env.PC_WORKERS_ROOT = roots;
+    }
+    env.PC_GATE_EVERY = env.PC_GATE_EVERY || "3";
+    env.PC_DEADLINE_MIN = env.PC_DEADLINE_MIN || "120";
+    env.PC_MAX_STORIES = env.PC_MAX_STORIES || "3";
+    for (const [key, value] of Object.entries(values))
+        env[key] = value;
+    for (const name of ["stories", "envelopes", "handoffs", "decisions"])
+        fs.mkdirSync(path.resolve(cwd, values.PC_STATE, name), { recursive: true });
+}
+async function runConductor(args, current) {
+    const argv = current.args.length > 0 ? current.args : args;
+    const root = resolveLiveRoot({ hqRoot: current.parent?.parent?.opts().hqRoot });
+    if (!await coreNativePipelineEnabled()) {
+        const result = runBundledScript({ asset: PIPELINE_CONDUCTOR_ASSET, args: argv, cwd: process.cwd(), hqRoot: root, env: { PC_HQ_ROOT: root } });
+        if (result.code !== 0)
+            process.exit(result.code);
+        return;
+    }
+    const parsed = parseConductorArgs(argv);
+    if ("error" in parsed) {
+        process.stderr.write(parsed.usage ? CONDUCTOR_USAGE : parsed.error + " 2\n");
+        process.exit(2);
+    }
+    prepareNativeEnvironment(parsed.values, root, process.cwd());
+    const native = await import("./core-pipeline-conductor-native.js");
+    native.runPipelineConductorNative();
+}
+async function runDriver(args, current) {
+    const argv = current.args.length > 0 ? current.args : args;
+    const root = resolveLiveRoot({ hqRoot: current.parent?.parent?.opts().hqRoot });
+    if (!await coreNativePipelineEnabled()) {
+        const result = runBundledScript({ asset: PIPELINE_DRIVER_ASSET, args: argv, cwd: process.cwd(), hqRoot: root, env: { PC_HQ_ROOT: root } });
+        if (result.code !== 0)
+            process.exit(result.code);
+        return;
+    }
+    const native = await import("./core-pipeline-driver-native.js");
+    process.exitCode = await native.runPipelineDriverNative(argv, root);
+}
+export function registerCorePipelineRuntimeCommands(core) {
+    const pipeline = core.commands.find((candidate) => candidate.name() === "pipeline")
+        ?? core.command("pipeline").description("Pipeline orchestration runtime");
+    const conductor = pipeline.command("conductor").description("Route and supervise pipeline stories")
+        .helpOption(false).allowUnknownOption().allowExcessArguments(true).argument("[args...]")
+        .action(async (args, _options, current) => runConductor(args, current));
+    const driver = pipeline.command("driver").description("Run the detached pipeline queue driver")
+        .helpOption(false).allowUnknownOption().allowExcessArguments(true).argument("[args...]")
+        .action(async (args, _options, current) => runDriver(args, current));
+    describeCoreCommand(conductor, { execution: "native", asset: PIPELINE_CONDUCTOR_ASSET, root: "live" });
+    describeCoreCommand(driver, { execution: "native", asset: PIPELINE_DRIVER_ASSET, root: "live" });
+}
+//# sourceMappingURL=core-pipeline-conductor-command.js.map

package/dist/commands/core-pipeline-conductor-native.d.ts

@@ -0,0 +1,7 @@
+export declare function isPipelinePathAbsolute(candidate: string, platform?: NodeJS.Platform): boolean;
+export declare function isPipelinePathUnder(candidate: string, root: string, platform?: NodeJS.Platform): boolean;
+export declare function resolvePipelineWorktreeTarget(candidate: string, platform?: NodeJS.Platform, cwd?: string): string;
+export declare function joinPipelinePath(a: string, parts: readonly string[], platform?: NodeJS.Platform): string;
+export declare function samePipelineRepositoryPath(gitTopLevel: string, repo: string, platform?: NodeJS.Platform): boolean;
+export declare function runPipelineConductorNative(): void;
+//# sourceMappingURL=core-pipeline-conductor-native.d.ts.map