@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.150

package/dist/cli/command-metadata.js

@@ -0,0 +1,232 @@
+import { commandInputs, commandAliases, physicalPathOptions } from "./command-inputs.js";
+import { runtimeOptionDescriptions } from "./command-option-descriptions.js";
+const optionDescriptions = {
+    "intake-sha256": "SHA-256 of the exact original intake file bytes. Fresh execution verifies the bytes; replay compares the retained hash without reopening the original file.",
+    "stage-profile": "Repeatable stage=profile assignment for the six mb-init stages. Each stage may occur once; the selected profile ID or alias is frozen before dispatch.",
+    "work-profile": "Repeatable approved Work executor profile ID or alias. Explicit order is retained; duplicate profiles refuse.",
+    "git-route": "Explicit project Git integration route. Direct integration uses the integration branch checkout; feature_worktree uses an already assigned separate checkout.",
+    "integration-branch": "Explicit project integration branch, validated with Git before project publication. No branch is inferred from the current checkout.",
+    "detach": "Return the accepted managed-controller receipt without observing until completion. Disconnecting the observer never stops the controller.",
+    "harness": "Select one supported harness family. Static discovery checks executable presence, not authentication or model access; diagnostics require separate effect consent.",
+    "provider": "Exact provider namespace for model filtering or doctor observation binding, including namespaced IDs such as builtin:zai-coding-plan. An account binding requires --account-sha256; this selector does not authenticate credentials.",
+    "executable": "Explicit installed harness executable path, including paths with spaces. Resolves ambiguous installations without choosing an arbitrary PATH candidate. Discovery never executes it; probes require explicit effect flags.",
+    "state-dir": "Existing OpenCode server state directory for the selected doctor. Its daemon configuration must bind the selected executable; doctor does not start or stop an unrelated daemon. Not an executor profile or project directory.",
+    "model-observation-file": "Optional destination for a standalone model listing snapshot from the admitted doctor. Requires --provider and --account-sha256; operator scope is unverified. Artifact publication is explicit, separate from provider writes, and never proves account access. Must differ from --response-file.",
+    "save-profile-intent": "Explicit frozen dd-flow/profile-creation-intent@1 JSON file containing before/after settings, profile and default consent. Setup binds it to request identity, saves under revision CAS and reconciles exact replay. Conflicts with --skip-agent-setup; an additional selected profile must match. This file is not provider authorization.",
+    "set-default": "Explicitly select the newly created profile as global default in the same atomic settings write. Omission preserves the existing default. Does not change frozen RUN settings.",
+    "remove": "Remove the positional operator alias binding, not its target profile; conflicts with --target.",
+    "clear": "Clear the operator global default without removing profiles or changing project routing and frozen RUN snapshots.",
+    "allow-processes": "Explicit permission to execute installed diagnostic code. Version/doctor probes are opt-in; static discovery never requires this flag.",
+    "allow-services": "Permit the selected adapter doctor's possible service process effects. Does not authorize model Turns, a flow, or reuse of an unrelated service.",
+    "allow-credentials": "Permit possible credential reads by the installed diagnostic; no credentials or raw adapter output enter this command's result.",
+    "allow-writes": "Permit possible diagnostic temporary/runtime writes by installed code; not permission to modify project packs or RUN settings.",
+    "native-executable": "Absolute native ZCode executable for the selected ZCode ACP doctor; no ambient ZCODE_BIN fallback. Invalid for other families.",
+    "timeout-ms": "Timeout in milliseconds for the selected operation. Harness diagnostics accept 1..60000: version defaults to 3000 and doctor to 30000. Other commands retain their own operation timeout policy; this option is not a productive RUN inactivity policy.",
+    "seed-file": "Optional reviewed dd-flow/model-catalog@1 JSON input; default is the bundled seed. Seed-only entries cannot establish account access or runtime qualification.",
+    "observation-file": "Explicit regular-file model listing snapshot; requires --harness, --provider and --account-sha256. Foreign scopes are ignored; malformed or secret-bearing fields refuse. No live listing is started.",
+    "account-sha256": "Opaque 64-character lowercase SHA-256 account binding, never an account name, token or credential path. Requires --harness and --provider; does not authenticate the account.",
+    "canon-source": "Explicit local signed release bundle or HTTPS envelope URL. Remote archives must use the same origin; trust comes only from --trust-file. Exclusive with --canon-version.",
+    "canon-version": "Exact canon release version in the selected channel of the operator release registry; exclusive with --canon-source. Omission selects the registry's explicit channel default.",
+    "release-registry": "Operator dd-flow/release-registry@1 JSON selector; default is DD_FLOW_RELEASE_REGISTRY or release-registry.json in DD_FLOW_HOME. Registry entries never enroll signing keys.",
+    "trust-file": "Explicit operator dd-flow/release-trust@1 file; release bytes cannot enroll their own signing key.",
+    "channel": "Selected release channel; preview and development must be requested explicitly.",
+    "skip-agent-setup": "Install without selecting or configuring an executor; conflicts with --profile.",
+    "non-interactive": "Never request interactive input; a missing executor selection fails unless agent setup is explicitly skipped.",
+    "project-root": "Stable repository identity; not the assigned feature workspace.",
+    "workspace-root": "Concrete assigned checkout used for this operation.",
+    "workspace-path": "Concrete assigned checkout; does not change project identity.",
+    "root": "Explicit root for the selected command; prevents implicit root discovery.",
+    "run": "Exact retained RUN identity; its frozen execution settings remain authoritative.",
+    "reason": "Operator explanation retained with the requested change.",
+    "request-id": "Stable request identity for reconciliation and idempotent retry.",
+    "request-key": "Stable exact-request replay identity; changed inputs or missing independent custody refuse rather than allocate again. The owning command defines scope and syntax.",
+    "expected-revision": "Required current revision; stale changes are rejected instead of overwriting concurrent edits.",
+    "profile": "Explicit configured profile identifier; credentials are not stored in profiles.",
+    "profile-file": "Complete validated executor profile; exclusive with --profile and --skip-agent-setup. Does not change operator defaults.",
+    "agent-profile": "Explicit configured executor profile; no automatic model selection.",
+    "force": "Explicit force request; does not bypass ownership, compatibility or authorization gates.",
+    "offline": "Explicit drained/offline operation; does not establish physical settlement by itself."
+};
+/** Option names alone are insufficient when different commands own different inputs. */
+const memoryRepairOptions = {
+    run: "Active registered mb-init review RUN; retained correction graph and frozen execution own every repair operation.",
+    wave: "Exact causal correction wave 1 or 2; never falls back to another wave or permits a third wave.",
+    work: "Exact registered repair Work in the selected correction wave; foreign Work and generation custody refuse.",
+    "workspace-root": "Shared frozen RUN workspace, not the private repair copy; independent source and scope custody remain required.",
+    "work-session": "Exact independently started repair WorkSession; this command never creates or claims a provider Session."
+};
+const memoryInitOptions = {
+    "prepare-only": "Prepare or replay the frozen Memory RUN and project bootstrap without launching a controller or provider Session. This publishes project/runtime state; it is not a dry run. Use run drive launch with the returned RUN to select bounded observation/capture. Exclusive with --detach; replay never stops an existing controller.",
+    "profile-file": "Absolute regular JSON file with one complete validated operation-only executor profile. Exclusive with --profile; never saves settings or changes defaults. Omit on replay to reuse frozen bytes; supplied profile content must match the original selection.",
+    "non-interactive": "Never open the first-flow executor dialog, even on a terminal. Without an explicit profile/file or configured default, refuse before project effects; init cannot skip its executor."
+};
+const commandOptionDescriptions = {
+    "flow mb-audit": {
+        "project-root": "Canonical absolute project identity. The runtime creates an isolated read-only source snapshot; neither the project nor its Memory Bank is a write destination.",
+        "intake-file": "Bounded UTF-8 original diagnostic request, including audit mode/focus and constraints. Required for a fresh request; optional on exact replay, where supplied bytes must match.",
+        "stage-profile": "Repeatable preflight/audit/review/report=profile override. Each stage may occur once and all profiles are frozen before dispatch.",
+        "prepare-only": "Retain the request, source snapshot and RUN without starting its controller or provider Sessions. Runtime state is created; this is not a dry run.",
+        "max-parallel": "External Work concurrency from 1 to 64; default 1. Never claims native child qualification."
+    },
+    "flow project-review": {
+        "project-root": "Canonical absolute project identity, assessed through an isolated read-only snapshot. Findings never authorize implicit repair.",
+        "intake-file": "Bounded UTF-8 original project-conformance review request and focus. Required fresh; supplied replay bytes must match the retained objective.",
+        "stage-profile": "Repeatable preflight/analyze/review/report=profile override. This is project review, not the SDLC CODE-REVIEW stage.",
+        "prepare-only": "Retain the request, source snapshot and RUN without launching a controller or provider Sessions. Not a dry run.",
+        "max-parallel": "External Work concurrency from 1 to 64; default 1."
+    },
+    "flow mb-init": memoryInitOptions,
+    init: memoryInitOptions,
+    "flow mb-upgrade": { ...memoryInitOptions, "stage-profile": "Repeatable stage=profile assignment for preflight, diff-analysis, upgrade, verify, review or finish. The original selection is frozen before dispatch.", "prepare-only": "Prepare or replay the upgrade RUN and accepted storage/bootstrap selection without launching its controller or a productive Session. This is not a dry run; it does not publish the upgraded canonical layer or accept semantic preservation." },
+    upgrade: { ...memoryInitOptions, "stage-profile": "Repeatable stage=profile assignment for preflight, diff-analysis, upgrade, verify, review or finish. The original selection is frozen before dispatch.", "prepare-only": "Prepare or replay the upgrade RUN and accepted storage/bootstrap selection without launching its controller or a productive Session. This is not a dry run; it does not publish the upgraded canonical layer or accept semantic preservation." },
+    "runtime storage admit": { operation: "Operation-specific writable-connection admission: memory-init or memory-upgrade. Upgrade also checks retained request storage. Requires explicit canonical DD_FLOW_HOME and an existing compatible resource registry. Never initializes, migrates, repairs or starts agents." },
+    "runtime storage qualify": { operation: "memory-upgrade only. Qualify the selected engine before a native probe. Incompatible drained stores are copied privately with committed WAL; the actual transition and operation admission run on those copies. Requires both explicit canonical Homes. Never migrates real stores, grants productive admission, creates a RUN or starts agents." },
+    "runtime flow admit": { operation: "Handler admission for memory-init or memory-upgrade in the executing engine. Reads bounded UTF-8 JSON stdin with source and source_sha256; memory-init additionally accepts startup_input_schema to require its startup reader. Validates the matching six-stage descriptor using actual registered handlers. Does not establish release trust, storage/provider readiness or semantic completion, and never creates Home, RUN or agents." },
+    "profiles create": { file: "Regular UTF-8 JSON file containing one complete validated agent profile. The ID must be unused. Credentials and unknown fields are refused; creation uses --expected-revision and never starts a model Turn." },
+    "profiles edit": { file: "Regular UTF-8 JSON file containing the complete replacement agent profile, not a patch. Its ID must already exist. Revision conflicts refuse the edit; retained RUN snapshots are unchanged." },
+    "profiles alias": {
+        target: "Existing canonical profile ID for the positional alias. Aliases cannot chain or collide with profile IDs. Supply exactly one of --target or --remove, plus --expected-revision.",
+        remove: "Remove the positional alias, not its target profile. Exclusive with --target. The revision-checked change does not rewrite retained RUN settings."
+    },
+    "profiles set-default": { clear: "Clear only the operator global default. Exclusive with a positional profile ID or alias; existing profiles, project routing and frozen RUN settings remain unchanged." },
+    "work add-batch": {
+        file: "Validated Work batch JSON file declaring children of --parent, including their task and dependency inputs. Adding logical Work does not launch physical Sessions.",
+        stage: "Explicit owner stage. With --request-key it must be the active running coordinator stage; attempt and cycle are resolved from retained RUN authority.",
+        "request-key": "Stable registration ID (1..96 letters, digits, dots, underscores or hyphens, starting with a letter or digit). Requires --stage. Identical replay returns the retained Work IDs; changed input or missing custody refuses allocation. Without this option the historical non-replayable batch behavior is retained."
+    },
+    "schema validate": { file: "JSON document to validate against --schema in the selected schema directory. Validation does not execute a flow or accept semantic completion." },
+    "migration verify": { file: "Existing dd-flow/mb-upgrade-migration-report@1 JSON report to verify against migration evidence; verification does not apply a storage migration." },
+    "migration readiness": {
+        "request-id": "Stable upgrade request ID. Retains a physically verified content-only storage proof; identical replay reuses it and changed inputs refuse. Does not create a RUN, sync content or migrate stores.",
+        "workspace-root": "Existing canonical absolute assigned workspace. Recorded with the project and request; this storage-only operation does not establish Git/workspace eligibility for the full upgrade.",
+        "project-root": "Registered active project requiring a complete release-impact chain and valid current provenance. Existing compatible run/resource stores are mandatory; this command never initializes or repairs them. Explicit mb-upgrade mode is required."
+    },
+    "migration apply": { file: "Explicit migration report JSON file used for admission to the requested apply operation; backup and ownership gates remain mandatory." },
+    "prompt render": { profile: "Prompt profile name required by the assigned Work execution context; not an operator executor profile ID or a Codex home profile." },
+    "runtime process register": { harness: "Harness family associated with the registered process/budget; registration is not a discovery or doctor probe.", "state-dir": "Adapter runtime state directory retained with the physical process for later ownership/admission checks." },
+    "runtime process admission": { "state-dir": "Exact adapter runtime state directory matching the confirmed process record; mismatched ownership refuses provider admission." },
+    "runtime process release-turn": { "observation-file": "Provider turn release observation file for the selected daemon/operation budget. This is not a model inventory snapshot or account listing." },
+    "runtime scope control": { mode: "Recoverable scope control intent: pause or stop. Drain/settlement remains pending until owned physical evidence is confirmed." },
+    "merge request route": { mode: "Route this MERGE request through same_session or server; selected execution policy and workspace admission still apply." },
+    "worktree close": { mode: "keep retains the feature checkout; remove requests its guarded removal. Dirty or foreign worktrees must not be silently discarded." },
+    "codex home remove": { mode: "keep-shared preserves shared state; remove-owned removes only the verified project-owned home entries.", profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
+    "codex home plan": { profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
+    "codex home init": { profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
+    "codex home status": { profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
+    "codex home print-env": { profile: "Isolated project Codex home profile name, not an executor agent-profile ID." },
+    "codex hooks print": { target: "Hook installation target: isolated (default) or default Codex home. Printing does not install hooks.", profile: "Project Codex home profile used to locate isolated hooks; not an executor profile." },
+    "codex hooks status": { target: "Hook installation target: isolated (default) or default Codex home. Status does not install hooks.", profile: "Project Codex home profile used to locate isolated hooks; not an executor profile." },
+    "codex hooks install": { target: "Hook installation target: isolated (default) or default Codex home; mutation also requires explicit confirmation.", profile: "Project Codex home profile used to locate isolated hooks; not an executor profile." },
+    "codex hooks remove": { target: "Hook installation target: isolated (default) or default Codex home; removal also requires explicit confirmation.", profile: "Project Codex home profile used to locate isolated hooks; not an executor profile." },
+    "protocol sync-from-run": { target: "Protocol state target derived from the selected RUN; auto uses the command's supported state mapping." },
+    "run reconcile": {
+        apply: "Persist the observed RUN health under its current ownership and revision fences. Without this switch, report only; never launch, resume or stop a provider.",
+        "no-progress-ms": "Override the health-assessment progress-age threshold in milliseconds; integer at least 1000. Defaults are 120000 for starting, 300000 for capturing and 1800000 otherwise. This is not a productive command timeout or permission to stop a live owner."
+    },
+    "run fork": { from: "Existing retained snapshot path to fork into a new RUN with the explicitly selected engine; not a control request identity." },
+    "run control resume": { from: "Exact retained pause/stop control ID whose captured state authorizes this resume request; not a snapshot path." },
+    "stage block": { kind: "Blocker category: engine, harness or environment; code and summary identify the actionable cause." },
+    "migration impact": { mode: "Optional full_migration request forces the strict full-migration assessment; otherwise impact evidence determines patch, targeted_minor or full_migration." },
+    "runtime storage transition": {
+        "selection-sha256": "Exact independently retained full upgrade selection; checked before any storage effect. Commands issued by the selected engine include this value.",
+        action: "Selected frozen engine transport: plan retains the pair; apply performs its explicit cutover; status observes it. recovery-plan selects and fences separate recovery; recover executes it; recovery-status observes recovery. No command starts a model or RUN.",
+        "expected-sha256": "Exact retained migration request SHA for apply/status/recovery-plan, or retained recovery request SHA for recover/recovery-status. Not a fresh selector or permission to replace a request.",
+        "recovery-id": "Explicit recovery identity (1..86 safe ASCII characters); required only for recovery-plan. Recovery aborts the original apply.",
+        offline: "Required for apply, recovery-plan and recover after all local/external writers are drained. The engine independently checks registered logical and physical owners; it never kills them.",
+        "project-root": "Original retained upgrade project identity. No project or database is initialized by this transport.",
+        "workspace-root": "Original assigned upgrade workspace; must match the frozen request.",
+        "request-id": "Original upgrade request identity; the engine and migration files come only from that request."
+    },
+    "memory permissions preflight": { mode: "Permission contour to check: read, write, repair or report_only; write checks may create temporary permission probes.", flow: "Workflow permission contour: mb-init, mb-upgrade, mb-audit, mb-fix, mb-upgrade-review or custom. Not a filesystem path." },
+    "memory compose register": { "run": "Active mb-init or mb-upgrade RUN whose accepted discovery/diff-analysis and immutable execution bind the composition graph.", "request-key": "Stable composition registration identity; exact replay retains the original Work graph.", "result-file": "Bounded proposed composition JSON. Bytes are prepared before registration; agent fields do not grant Work or write authority." },
+    "memory upgrade publish": { run: "Active mb-upgrade authoring Stage with a registered blueprint and settled Work. Apply only its retained canonical publication plan and recovery archive; this does not accept the Stage or complete the RUN." },
+    "memory verify checks": { "run": "Active mb-init or mb-upgrade RUN. Execute only its independently selected declared verification checks." },
+    "memory review register": { "run": "Active mb-init or mb-upgrade RUN with accepted verification. Register initial independent reviewers; this does not launch providers." },
+    "memory review collect": { "run": "Active mb-init or mb-upgrade RUN. Collect genuine registered initial-wave results without accepting the Stage or granting correction authority." },
+    "memory finish evidence": { "run": "Active mb-init or mb-upgrade finish RUN. Publish independently prepared coverage, integration and readiness evidence; publication does not complete Stage or RUN." },
+    "memory finish integrate": { "run": "Active mb-init or mb-upgrade finish RUN. Commit only accepted Memory Bank and owned lint files under retained Git policy, then integrate the admitted workspace locally. Preserve unrelated staged/dirty files; never push. Lost-response replay observes the original effects without another commit." },
+    "memory corrections register": { run: "Active mb-init or mb-upgrade review RUN. Register only the correction plan bound to the independently retained preceding review.", wave: "Correction wave 1 follows initial review; wave 2 requires settled first selective review. A third wave is unsupported.", "result-file": "Bounded correction-plan JSON prepared before graph registration; exact retained replay cannot substitute another plan." },
+    "memory corrections checks": { run: "Active mb-init or mb-upgrade review RUN with a genuinely settled correction view.", wave: "Run only the independently selected finite check profile for correction wave 1 or 2; this does not accept semantic quality." },
+    "memory review selective-register": { run: "Active mb-init or mb-upgrade review RUN. Allocate selective reviewers only after their wave's committed checks.", wave: "Select correction wave 1 or 2. Unaffected accepted units remain retained; registration does not launch providers." },
+    "memory review selective-collect": { run: "Active mb-init or mb-upgrade review RUN. Return genuine selective reviewer references, not Stage or RUN acceptance.", wave: "Select independently registered review of correction wave 1 or 2; missing wave custody never falls back to initial review." },
+    "memory repair baseline": { ...memoryRepairOptions, work: "Register the immutable prelaunch baseline for this repair Work; dependent/peer changes require explicit current-view registration first. Does not launch providers." },
+    "memory repair copy-reserve": { ...memoryRepairOptions, work: "Reserve the owned private copy for this repair Work after its committed baseline; reservation does not create the copy or launch providers." },
+    "memory repair copy-materialize": { ...memoryRepairOptions, work: "Materialize the reserved private copy for this repair Work with retained build/ready receipts; no provider launch or shared document publication." },
+    "memory repair copy-dispatch": { ...memoryRepairOptions, work: "Prepare the frozen profile and verified ready-copy root for this repair Work. Read-only packet output does not launch a provider, claim a Session or replace fresh launcher custody checks." },
+    "memory repair current-view": { ...memoryRepairOptions, work: "Retain the explained settled-peer input view for this repair Work; does not replace an existing immutable baseline or grant launch authority." },
+    "memory repair publication-source": { ...memoryRepairOptions, wave: "Wave 1 only: retain independently explained shared publication source before reserving output. Wave 2 uses its separate retained launch owner." },
+    "memory repair publication-reserve": { ...memoryRepairOptions, "result-file": "Bounded exact private repair result bytes prepared before dispatch. Reserve the independently validated delta only; wave 1 requires a previously registered publication-source." },
+    "memory repair publication-apply": { ...memoryRepairOptions, work: "Apply or reconcile one retained publication action for this repair Work; repeat until physical publication completes. Unknown effect never authorizes blind retry." },
+    "memory repair publication-finish": { ...memoryRepairOptions, work: "Settle this repair Work only after independently proven physical publication completion; does not accept semantic review or finish Stage/RUN." }
+};
+export const globalOptionDocumentation = [
+    { name: "help", description: "Show help before command preparation or resource access; -h is equivalent.", kind: "switch", required: false, repeatable: false, choices: [], physical_path: false },
+    { name: "option", description: "Help-only selector for one option; accepts name or --name.", kind: "value", required: false, repeatable: false, choices: [], physical_path: false },
+    { name: "json", description: "Emit structured JSON rather than human text.", kind: "switch", required: false, repeatable: false, choices: [], physical_path: false },
+    { name: "progress-jsonl", description: "Emit machine-readable progress events during command execution.", kind: "switch", required: false, repeatable: false, choices: [], physical_path: false },
+    { name: "response-file", description: "Execution-only response destination; help never opens or writes it.", kind: "value", required: false, repeatable: false, choices: [], physical_path: true }
+];
+export function optionsForCommand(input, command) {
+    return [...new Set([...input.values, ...input.switches])].map(name => ({
+        name,
+        description: optionDescription(name, command),
+        kind: input.switches.includes(name) ? "switch" : "value",
+        required: input.required.includes(name), repeatable: input.repeatable.includes(name),
+        choices: input.enums[name] ?? [], physical_path: physicalPathOptions.has(name) && name !== "flow" && name !== "stage"
+    }));
+}
+function optionDescription(name, command) {
+    const description = (command ? commandOptionDescriptions[command]?.[name]
+        ?? commandOptionDescriptions[commandAliases[command] ?? command]?.[name] : undefined) ?? optionDescriptions[name] ?? runtimeOptionDescriptions[name];
+    if (!description)
+        throw new Error(`Missing CLI option documentation: ${command ?? "inventory"} --${name}`);
+    return description;
+}
+/** Shared help/completion option set for a route, family or root catalog. */
+export function optionsForCommandTree(command) {
+    const options = new Map(globalOptionDocumentation.map(option => [option.name, option]));
+    for (const [key, input] of Object.entries(commandInputs)) {
+        if (!command || key === command || key.startsWith(`${command} `)) {
+            for (const option of optionsForCommand(input, key))
+                options.set(option.name, option);
+        }
+    }
+    return [...options.values()].sort((left, right) => left.name.localeCompare(right.name, "en"));
+}
+/** One exact native routing classification shared by router and compatibility admission. */
+export function routerNativeRoute(key) {
+    return key === "version" || key.startsWith("engine ") || key === "schema validate"
+        || key === "flow list" || key === "flow show" || key === "flow mb-init" || key === "init" || key === "flow mb-upgrade" || key === "upgrade"
+        || key === "flow mb-audit" || key === "flow project-review" || key === "review"
+        || key === "run reconcile" || key === "runtime storage admit" || key === "runtime storage qualify" || key === "runtime storage transition"
+        || key === "runtime flow admit"
+        || key.startsWith("profiles ") || key.startsWith("models ") || key.startsWith("harnesses ") || key.startsWith("completion ") || key === "setup" || key.startsWith("setup ")
+        || key === "storage migrate-writer" || key === "codex hook handle"
+        || key === "zcode hook handle" || key === "zcode invocation prepare"
+        || /^(zcode|grok|droid|opencode|agy) (event handle|usage ingest)$/.test(key);
+}
+export function commandKeyForPositions(positions) {
+    return Object.keys(commandInputs).filter(key => key.split(" ").every((part, index) => positions[index] === part))
+        .sort((a, b) => b.split(" ").length - a.split(" ").length)[0];
+}
+/** Best matching help topic for rejected argv; never validates or executes it.
+ * Option values and literal passthrough cannot impersonate a command path.
+ */
+export function commandHelpTopic(args, fallback) {
+    const switches = new Set([...globalOptionDocumentation.filter(option => option.kind === "switch").map(option => option.name),
+        ...Object.values(commandInputs).flatMap(input => input.switches)]);
+    const positions = [];
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--")
+            break;
+        if (arg.startsWith("--")) {
+            const name = arg.slice(2).split("=", 1)[0];
+            if (!arg.includes("=") && !switches.has(name) && args[index + 1] && !args[index + 1].startsWith("-"))
+                index++;
+        }
+        else if (!arg.startsWith("-"))
+            positions.push(arg);
+    }
+    return commandKeyForPositions(positions) ?? fallback;
+}

package/dist/cli/command-option-descriptions.js

@@ -0,0 +1,192 @@
+/** Reviewed meanings for existing runtime options. Grammar owns requiredness,
+ * repetition and enumerations; these descriptions do not grant effect authority.
+ */
+export const runtimeOptionDescriptions = {
+    "acquire-lock": "Boolean: acquire the workspace lane lock when claiming the next merge job; waiting alone does not grant ownership.",
+    "adapter-executable": "Executable path retained with the registered adapter process for ownership and later reconciliation.",
+    after: "Timeline cursor for controller status; return observations after this sequence number.",
+    alias: "Additional report alias to retain with the completed stage; repeat for multiple aliases.",
+    all: "Refresh dashboards for all selected projects rather than only the current project.",
+    "allow-downgrade": "Explicitly permit lowering flow flags during a revision-checked change; other admission gates still apply.",
+    "answer-file": "File containing the user's answer for the selected paused stage or drive request; not a replacement task or execution policy.",
+    "answer-stdin": "Read the stage answer from standard input instead of --answer-file.",
+    apply: "Apply the proposed project-ID migration; without this switch the command remains a preview.",
+    "available-slots": "Record available native delegation capacity as an integer from 0 through 15; capacity is not proof of child settlement.",
+    "max-parallel": "Freeze the Work concurrency limit (external integer 1..256; explicit native 1..15). Omit on replay to retain the original selection; native capacity requires an authorized technical probe and never overrides runtime budgets or Work dependencies.",
+    "delegation": "Select external Work sessions (default) or explicit native children. Native fresh init requires --allow-live-probe; it cannot switch worker profiles.",
+    "allow-live-probe": "Authorize this request's bounded technical native child probe outside the RUN. It can incur provider usage; unknown effects retain exact operation custody and never restart fan-out.",
+    "native-config-home": "Optional absolute provider configuration home for native qualification. Otherwise preserve normal harness authentication and configuration. The CLI never copies or links credentials or rewrites operator configuration.",
+    backup: "New absolute backup destination for the explicitly drained database; an existing backup is never overwritten.",
+    "backup-created-at": "Timestamp of the retained backup used as migration evidence; must agree with the selected migration inputs.",
+    "backup-path": "Path to the retained backup bound into migration planning, reporting or application evidence.",
+    base: "Git base reference from which the requested feature worktree is created.",
+    bootstrap: "Request the supported initial stage bootstrap rather than starting a stage on an existing RUN; still requires declared intake and admission.",
+    branch: "Git branch assigned to the selected workspace or worker; a branch name does not itself authorize creation or merge.",
+    "budget-json": "Inline JSON declaration of runtime process budget; validated by the process owner before registration.",
+    "cancel-queue": "Boolean: cancel protocol queue entries as part of cancellation; does not silently settle running workers.",
+    candidate: "Mark the created snapshot as a recovery candidate rather than claiming accepted restoration.",
+    "capture-key": "Exact retained capture digest selecting the recovery state for the requested scope generation.",
+    "capture-path": "Destination for the selected RUN recovery capture; capture is distinct from accepting recovery.",
+    "capture-root": "Root directory for controller recovery captures associated with this drive request.",
+    check: "Check identity associated with a registered runtime process, preserving its ownership scope.",
+    "check-ref": "Retained check evidence reference motivating repair Work; repeat to bind multiple checks.",
+    "check-registry": "Include project registry consistency diagnostics in status; does not repair the registry.",
+    "close-sessions": "Boolean: request closing protocol Sessions during cancellation; physical completion requires separate evidence.",
+    code: "Stable diagnostic code for the engine, harness or environment blocker being recorded.",
+    command: "Command to launch as the owned runtime service, with declared ports and readiness checks.",
+    "context-file": "Prepared context file for the selected stage/controller request; its bytes must match --context-sha256.",
+    "context-sha256": "SHA-256 of the exact --context-file bytes, preventing substitution of prepared context.",
+    "control-id": "Retained RUN control request identity used by its owner or reconciliation command.",
+    "controller-id": "Retained drive controller identity; does not create an unrelated controller or bypass ownership.",
+    "daemon-id": "Selected provider daemon identity for scoped admission or recovery; not a request to start an arbitrary daemon.",
+    dashboard: "Dashboard artifact path associated with the completed stage.",
+    data: "Stage data artifact path supplied for validation and completion; its applicable schema is independently selected.",
+    "data-schema-id": "Registered schema identity for the stage data artifact; selecting a schema is not semantic acceptance.",
+    database: "Existing absolute SQLite database path to migrate; the command does not initialize a missing runtime database.",
+    "decision-file": "Retained stage decision artifact required by the selected finish contract.",
+    dir: "Stage artifact directory selected for attachment or lifecycle processing; must satisfy the selected stage's layout contract.",
+    "dispatch-barrier": "Retained dispatch barrier associated with the registered runtime process; not proof of productive admission.",
+    "engine-version": "Exact installed engine version selected for legacy binding recovery or a requested RUN fork.",
+    escalate: "Escalation policy for an owned pause/stop operation; does not authorize stopping unrelated processes.",
+    event: "Hook event name identifying the Codex event being handled; hook payload is validated separately.",
+    evidence: "Evidence reference supporting a completed plan item; repeat to retain multiple references.",
+    "execution-routing-file": "Validated execution routing JSON file used for the selected RUN creation or restoration; retained RUN profiles remain frozen.",
+    file: "JSON input file consumed by this command's declared validator; see the exact command topic for its contract.",
+    flag: "Explicit flow flag assignment for creation or revision; repeat for multiple assignments. Revision and policy gates still apply.",
+    flow: "Memory workflow whose permissions are checked; preflight does not execute that workflow.",
+    "flow-kind": "Flow kind recorded when creating the RUN; a label alone cannot register handlers or admit execution.",
+    format: "Dashboard output format; rendering and opening follow the selected command's supported formats.",
+    from: "Retained source identity for a fork or resume; its meaning is specified by the exact command topic.",
+    "from-check": "Check identity causing the repair Work, preserving traceability to the failed check.",
+    "from-finding": "Review finding identity motivating repair Work; repeat for multiple findings.",
+    "from-unresolved": "Unresolved issue identity motivating repair Work; repeat for multiple issues.",
+    generation: "Exact runtime scope generation; stale generations cannot admit recovery or new dispatch.",
+    global: "Read global dashboard data rather than one project dashboard.",
+    "grace-ms": "Grace period in milliseconds for an owned process or control stop before reconciliation/escalation.",
+    "group-by": "Usage aggregation dimension; grouping does not change source-backed usage evidence.",
+    hide: "Timeline event category to hide from the displayed view; repeat for multiple categories. Retained events are not deleted.",
+    "hook-event-id": "Trusted hook event identity binding this lifecycle invocation to its physical event.",
+    id: "Exact runtime process registry identity targeted by registration, lease operations or admission.",
+    "idempotency-key": "Stable flow-flag revision request key; retry the exact same change rather than applying it twice.",
+    "include-results": "Include retained Work result projections in the listing; listing remains an observation, not acceptance.",
+    incomplete: "Permit creation of an explicitly incomplete recovery snapshot; does not qualify it as a restorable complete snapshot.",
+    "intake-file": "File containing the raw user intake for initial stage bootstrap; do not replace it with an inferred solution.",
+    "intake-stdin": "Read raw bootstrap intake from standard input instead of --intake-file.",
+    "integrity-checksum": "Expected retained engine integrity checksum, checked independently of its version label.",
+    "interruption-json": "Inline JSON interruption evidence opening the selected RUN recovery attempt.",
+    "invocation-id": "Exact retained lifecycle invocation identity; syntax alone does not establish generation, ownership or authorization.",
+    "json-file": "JSON transition payload file; an alternative to the transition payload-file input.",
+    key: "Configuration or RUN variable key selected for reading or writing; supported configuration keys are validated by the owner.",
+    kind: "Classification of the recorded blocker or process; the exact command determines supported kinds.",
+    lane: "Named project workspace lane whose workspace, waiters or lock are being inspected or changed.",
+    "lease-ms": "Runtime process lease duration in milliseconds; renewal requires the current lease token.",
+    "lease-token": "Current owned lease token for the exact process or lane; not an executor credential or an ownership override.",
+    "registration-sha256": "Exact managed-process registration binding returned by confirmation or renewal. Pins the resource Home and registered owner/PID identity; a changed registration refuses rather than matching a reused process ID.",
+    limit: "Maximum number of Work entries returned by the listing; must be a positive integer.",
+    "manifest-json": "Inline runtime-scope manifest declaration binding the selected source manifest and executions; changed declarations refuse.",
+    "max-parallel-projects": "Maximum projects processed concurrently by the merge server; does not widen per-project merge authority.",
+    "memory-bank": "Memory Bank path whose access is checked by permission preflight; no installation or workflow is started.",
+    mode: "Operation mode accepted by this exact command; consult its allowed values and mode-specific effects.",
+    "native-session-id": "Existing physical provider Session identity for scoped recovery/admission; logical Work ancestry is separate.",
+    "next-action": "Explicit next-action projection stored with RUN creation or an operator override; it is not automatic dispatch.",
+    "observations-file": "Bounded observations JSON file for the selected fan-out/native scope; observations must satisfy ownership and settlement contracts.",
+    on: "Dependency Work identity to add or remove; repeat for multiple dependencies. Dependencies are not physical Session parentage.",
+    once: "Process one merge-server iteration instead of polling continuously.",
+    open: "Open the refreshed dashboard after rendering; does not alter RUN control state.",
+    operation: "Named operation associated with a registered process or provider admission request.",
+    "operation-id": "Exact retained provider operation identity bound to turn admission or release.",
+    "operational-decision-file": "Validated operational decision artifact authorizing the applicable snapshot restoration or fork route; not a release or arbitrary mutation permit.",
+    "origin-work": "Origin Work identity motivating repair; repeat to preserve multiple origins.",
+    outcome: "Outcome declared for the selected stage result; finish still validates its contract and evidence before transition.",
+    output: "Destination for a created snapshot, fork artifact or rendered dashboard; see the command's artifact contract.",
+    owner: "Runtime resource owner identity used for registration, admission or reconciliation; ownership is independently checked.",
+    "owner-pid": "Operating-system PID of the registered process owner, used for scoped liveness and reconciliation.",
+    package: "Engine package name used to locate the requested installed snapshot.",
+    parent: "Logical parent Work identity for batch creation or listing; does not make children physical subagents automatically.",
+    path: "Concrete workspace path used by lane, merge or worktree operations; not the stable project identity.",
+    "pause-id": "Exact retained user-interaction pause identity answered by this drive request.",
+    "payload-base64": "Base64-encoded Session registration payload; use only one payload transport.",
+    "payload-file": "File containing the selected transition or Session registration payload; validated before registration or transition.",
+    "payload-json": "Inline JSON Session registration payload; use only one payload transport.",
+    pid: "Operating-system PID of the registered physical process; a PID alone does not prove ownership or completion.",
+    "plan-file": "Previously generated cleanup plan file; application still checks its scope and explicit reason.",
+    "plan-item": "Plan item identity selected for the bounded worker prompt.",
+    "poll-interval": "Polling interval in seconds for lane/merge waiting; must be positive.",
+    "poll-seconds": "Merge server polling interval in seconds; must be positive.",
+    ports: "Comma-separated port declarations for the owned runtime service.",
+    preset: "Named flow-flag preset for creation or revision; explicit flag assignments and policy admission remain separate.",
+    "process-group-id": "Operating-system process-group identity retained for owned-tree cleanup; not a permit to kill unrelated groups.",
+    project: "Project selector for dashboard data, rendering or opening.",
+    "project-id": "Registered project identity associated with the physical runtime process.",
+    "prompt-sha256": "Digest of exact provider prompt bytes associated with operation admission.",
+    protocol: "Protocol selector limiting dashboard output to the requested protocol.",
+    "protocol-id": "Existing protocol identity whose feature worktree is planned, created, inspected or closed.",
+    "protocol-override-file": "Validated protocol override JSON input supplied at RUN creation; does not overwrite an existing frozen RUN.",
+    "question-file": "File containing the user question that pauses this stage/Work under the selected interaction contract.",
+    "question-stdin": "Read the stage question from standard input instead of --question-file.",
+    ready: "List dependency-ready Work entries rather than all entries; readiness does not launch them.",
+    "ready-path": "HTTP path used for the runtime service readiness check.",
+    "ready-port": "Declared service port used for the runtime readiness check.",
+    "ready-timeout-ms": "Maximum service readiness wait in milliseconds; must be a positive integer.",
+    "reason-file": "File containing the reason artifact required by the selected lifecycle finish contract.",
+    "recovery-id": "Exact retained RUN recovery attempt identity; recovery acceptance and physical settlement remain separate gates.",
+    "release-locks": "Boolean: request protocol lock release during cancellation; ownership checks still apply.",
+    report: "Report artifact path associated with the completed stage.",
+    request: "Retained request reference supplied to the selected stage finish contract; not a new setup request ID.",
+    requeue: "Boolean: put the failed merge job or bundle back in the queue; a failure is not converted into accepted merge evidence.",
+    "require-session-binding": "Require trusted physical Session binding before starting the stage; do not synthesize one from a RUN ID.",
+    "result-file": "Validated result JSON artifact for this stage or Work; process exit success is not a substitute for accepted result evidence.",
+    "result-stdin": "Read result JSON from standard input instead of --result-file.",
+    "retry-check": "Check identity requested for the selected bounded retry path; prior results cannot be reused without matching evidence.",
+    retryable: "Mark the recorded blocker as retryable; does not launch a retry or bypass the blocker.",
+    role: "Role metadata retained with the registered runtime process.",
+    schema: "Registered JSON schema name against which the supplied file is validated.",
+    "schema-dir": "Explicit schema directory for validation; not a workflow handler registry or permission to execute code.",
+    "scope-id": "Exact retained runtime/EVAL scope identity; operations must not affect neighboring scopes.",
+    "scope-ids-json": "Read-only JSON array of 1..16 unique retained scope IDs; returns ordered fresh inventories without fencing or stopping them.",
+    "semantic-file": "Stage semantic result artifact; applicable schema and finish checks are selected independently.",
+    session: "Physical Session selector for source-backed usage aggregation.",
+    "session-id": "Exact retained physical Session identity for registration, status, stop or usage synchronization.",
+    "settlement-json": "Inline JSON physical settlement evidence sealing a recovery attempt; logical inactivity alone is insufficient.",
+    slug: "Safe human-readable slug used for the new typed identifier or RUN.",
+    snapshot: "Existing snapshot artifact selected for bootstrap or RUN restoration; restored execution requires independent admission.",
+    "source-home": "Source Codex home used to plan or initialize the isolated project home; credentials remain operator-owned.",
+    "source-version": "Source Memory Bank version whose migration impact and evidence are being assessed.",
+    stage: "Stage identity within the selected flow/RUN; a name alone cannot admit a foreign stage.",
+    "stage-entry": "Stage entry selected for snapshot capture.",
+    "stage-report": "Stage report artifact path supplied for completion and retained observation.",
+    state: "Terminal state reported for the owned runtime process; supported values are shown below.",
+    status: "Work filter or declared stage/RUN state, depending on the exact command; lifecycle admission remains authoritative.",
+    stderr: "Retained standard-error log path associated with the registered process.",
+    stdout: "Retained standard-output log path associated with the registered process.",
+    "stop-after": "Stage boundary at which the drive controller should stop advancing; not proof of physical child settlement.",
+    subject: "Safe subject text for the bootstrap RUN; raw user intake is supplied separately.",
+    "subject-id": "Identity of the protocol or other subject associated with the new RUN.",
+    "subject-type": "Type of subject associated with RUN creation; it does not select an executor.",
+    summary: "Human summary retained with plan-item or merge completion/note evidence.",
+    "summary-file": "File containing the diagnostic summary for a stage blocker.",
+    "summary-stdin": "Read the blocker summary from standard input instead of --summary-file.",
+    target: "Destination selector for protocol synchronization or hook management; see the exact command topic.",
+    "target-home": "Destination isolated Codex home used by the project home plan/init operation.",
+    "target-version": "Target Memory Bank version selected for migration impact, planning or application.",
+    "task-file": "Bounded worker task artifact used for prompt rendering or repair Work creation.",
+    "task-profile-file": "Validated task-profile JSON input used when freezing a new RUN's task policy.",
+    "task-stdin": "Read repair task content from standard input instead of --task-file.",
+    tasks: "Task directory whose access is checked by Memory Bank permission preflight.",
+    timeout: "Maximum lane/merge waiting duration in seconds; not a provider model timeout.",
+    to: "Requested protocol lifecycle target; transition requirements are validated before changing state.",
+    ttl: "Lane lease lifetime in seconds; expiry does not by itself prove physical process settlement.",
+    type: "Typed identifier family whose next identifier is being previewed.",
+    "user-required": "Boolean indicating that the blocked plan item requires a user decision.",
+    value: "Configuration or RUN variable value to store under --key; configuration-specific validation still applies.",
+    verdict: "Operator override verdict projection; cannot turn an override into ordinary semantic acceptance.",
+    "verification-file": "Verification evidence artifact required by the selected stage finish or repair provenance contract.",
+    version: "Exact engine package version to inspect; omitted selection follows the engine-info command's existing resolver.",
+    viewer: "Viewer requested for opening the rendered dashboard.",
+    "wait-ms": "Maximum observation wait in milliseconds for the requested RUN control operation; timeout is not terminal settlement.",
+    work: "Exact Work identity within the selected RUN/stage or associated with a registered process/merge request.",
+    "worker-id": "Worker identity bound to the selected Session, lane lease or merge claim; not a model/profile selector.",
+    worktree: "Worktree handling policy requested during protocol cancellation; project ownership and cleanup guards still apply.",
+    write: "Boolean: publish the project summary instead of only returning its current projection.",
+    yes: "Explicit confirmation for hook installation/removal; does not bypass project access or target validation."
+};

package/dist/cli/completion-cli.js

@@ -0,0 +1,70 @@
+import { completionCandidates } from "./completion.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { writePreparationError } from "./error-output.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+export function completionScript(shell) {
+    if (shell === "bash")
+        return `# dd-flow completion: bash
+_dd_flow_complete() {
+  local candidate
+  COMPREPLY=()
+  while IFS= read -r candidate; do
+    [ -n "$candidate" ] && COMPREPLY+=("$candidate")
+  done < <("${"$"}{COMP_WORDS[0]}" completion candidates -- "${"$"}{COMP_WORDS[@]:1:COMP_CWORD}")
+}
+complete -o default -F _dd_flow_complete dd-flow
+`;
+    if (shell === "zsh")
+        return `#compdef dd-flow
+_dd_flow_complete() {
+  local -a replies
+  replies=("${"$"}{(@f)$("${"$"}{words[1]}" completion candidates -- "${"$"}{(@)words[2,CURRENT]}")}")
+  if (( ${"$"}{#replies} )) && [[ -n "$replies[1]" ]]; then
+    compadd -a replies
+  else
+    _files
+  fi
+}
+compdef _dd_flow_complete dd-flow
+`;
+    if (shell === "fish")
+        return `function __dd_flow_candidates
+  set -l tokens (commandline -opc)
+  set -l prefix (commandline -ct)
+  set -l arguments
+  if test (count $tokens) -gt 1
+    set arguments $tokens[2..-1]
+  end
+  $tokens[1] completion candidates -- $arguments "$prefix"
+end
+complete -c dd-flow -a '(__dd_flow_candidates)'
+`;
+    throw new AppError("usage", "Supported completion shells: bash, zsh, fish", 2, { effect: "no_effect" });
+}
+/** Completion is grammar-only: never constructs an AppContext or writes a home. */
+export function runCompletionCli(args, io = { stdout: process.stdout, stderr: process.stderr }) {
+    let json = false;
+    try {
+        const output = parseOutputOptions(args);
+        json = output.json;
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const route = prepareCommandRoute(output.args);
+        if (route.key === "completion candidates") {
+            const candidates = completionCandidates(route.parsed.positional);
+            io.stdout.write(json ? `${JSON.stringify(writeResponseFile({ candidates }, output))}\n` : candidates.map(value => `${value}\n`).join(""));
+        }
+        else {
+            const script = completionScript(route.command);
+            io.stdout.write(json ? `${JSON.stringify(writeResponseFile({ shell: route.command, script }, output))}\n` : script);
+        }
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/completion.js

@@ -0,0 +1,57 @@
+import { commandInputs } from "./command-inputs.js";
+import { globalOptionDocumentation, optionsForCommandTree } from "./command-metadata.js";
+const globalSwitches = globalOptionDocumentation.filter(option => option.kind === "switch").map(option => `--${option.name}`);
+const globalValues = globalOptionDocumentation.filter(option => option.kind === "value").map(option => `--${option.name}`);
+/** Read-only completion grammar. Last word is the cursor's unfinished token. */
+export function completionCandidates(words) {
+    const prefix = words.at(-1) ?? "";
+    const completed = words.slice(0, -1);
+    if (completed.includes("--"))
+        return [];
+    const positions = [];
+    let awaiting;
+    let routeKey;
+    const keys = Object.keys(commandInputs).filter(key => !commandInputs[key].retired);
+    const select = () => keys.filter(key => key.split(" ").every((part, index) => positions[index] === part))
+        .sort((left, right) => right.split(" ").length - left.split(" ").length)[0];
+    for (const word of completed) {
+        if (awaiting) {
+            awaiting = undefined;
+            continue;
+        }
+        if (word.startsWith("--")) {
+            const name = word.slice(2).split("=")[0];
+            const input = routeKey ? commandInputs[routeKey] : undefined;
+            const values = input?.values ?? [...new Set(Object.values(commandInputs).flatMap(item => item.values))];
+            if (!word.includes("=") && (values.includes(name) || globalValues.includes(`--${name}`)))
+                awaiting = name;
+            continue;
+        }
+        if (word === "-h")
+            continue;
+        positions.push(word);
+        routeKey = select();
+    }
+    const input = routeKey ? commandInputs[routeKey] : undefined;
+    let candidates;
+    const inline = prefix.match(/^--([^=]+)=(.*)$/);
+    if (awaiting || inline) {
+        const option = awaiting ?? inline[1];
+        candidates = option === "option" ? optionsForCommandTree(routeKey ?? positions.join(" ")).map(item => item.name)
+            : [...(input?.enums[option] ?? [])];
+        if (option === "option" && (inline?.[2] ?? prefix).startsWith("--"))
+            candidates = candidates.map(name => `--${name}`);
+        if (inline)
+            return candidates.filter(value => value.startsWith(inline[2])).map(value => `--${option}=${value}`).sort();
+    }
+    else if (prefix.startsWith("-")) {
+        candidates = [...globalSwitches, ...globalValues, ...(input ? [...input.values, ...input.switches].map(name => `--${name}`) : [])];
+    }
+    else {
+        candidates = keys.filter(key => {
+            const tokens = key.split(" ");
+            return positions.every((part, index) => tokens[index] === part) && tokens.length > positions.length;
+        }).map(key => key.split(" ")[positions.length]);
+    }
+    return [...new Set(candidates)].filter(value => value.startsWith(prefix)).sort();
+}