@indigoai-us/hq-cli 5.138.0 → 5.140.0

package/dist/lib/work-context/contract.d.ts

@@ -61,6 +61,14 @@ export interface ContextResult {
     bindingEpisodeId?: string;
     clientOperationId: string;
     errorCode?: string;
+    /** Why a project was chosen, or why the session is asking. Local consumers only. */
+    projectBindReason?: string;
+    /** Ranked alternatives when classification is needs_project. */
+    projectCandidates?: Array<{
+        projectId: string;
+        title?: string;
+        score?: number;
+    }>;
 }
 export type NormalizeTaskIdResult = {
     ok: true;

package/dist/lib/work-context/reconcile.d.ts

@@ -69,6 +69,15 @@ export interface ReconcileDeps {
      * companyUid when local resolution only yielded a slug. Injectable for tests.
      */
     validateMembership?: (slug: string) => Promise<MembershipValidationResult> | MembershipValidationResult;
+    /**
+     * Register a Board and PUT the local PRD. Called only when online and the
+     * exact slug already has a local project folder.
+     */
+    ensureProjectBoard?: (input: {
+        companyUid: string;
+        projectId: string;
+        prdPath: string;
+    }) => Promise<void>;
 }
 export interface ReconcileOutcome {
     result: ContextResult;

package/dist/lib/work-context/reconcile.js

@@ -9,6 +9,7 @@ import { invalidateDefaultCompanyMemberships, } from "./config.js";
 import { WORK_CONTEXT_CONTRACT_VERSION, normalizeTaskId, } from "./contract.js";
 import { EXIT_INVALID_IDENTITY, EXIT_NOT_TRACKING, EXIT_OK, InvalidDecisionOriginError, NotTrackingError, } from "./errors.js";
 import { decisionFromCandidates, } from "./organize.js";
+import { refineProjectBinding } from "./bind-best.js";
 import { resolveProjectTask, shouldAskAfter } from "./project.js";
 import { deriveRemoteOwnerSlug, deriveRepoIdentityKey } from "./repo-remote.js";
 import { enqueueOutbox, listOutboxOperations, markOutboxAcked, markOutboxQuarantined, markOutboxQueued, replayOutbox, writeAckedRegisterState, } from "./outbox.js";
@@ -35,6 +36,10 @@ function resultOf(parts) {
         out.bindingEpisodeId = parts.bindingEpisodeId;
     if (parts.errorCode)
         out.errorCode = parts.errorCode;
+    if (parts.projectBindReason)
+        out.projectBindReason = parts.projectBindReason;
+    if (parts.projectCandidates)
+        out.projectCandidates = parts.projectCandidates;
     return out;
 }
 function parseUntrackedOrigin(obs) {
@@ -441,8 +446,77 @@ export async function reconcileObservation(obs, deps) {
             projectResolved = null;
         }
     }
-    const projectId = projectResolved?.projectId;
-    const taskId = projectResolved?.taskId;
+    let projectId = projectResolved?.projectId;
+    let taskId = projectResolved?.taskId;
+    let projectBindReason;
+    let projectCandidates;
+    let projectGate;
+    if (projectResolved &&
+        projectId &&
+        projectResolved.source !== "existing_binding" &&
+        obs.source !== "transcript" &&
+        hqRoot &&
+        resolvedCompany.slug) {
+        const refined = refineProjectBinding({
+            hint: projectId,
+            hqRoot,
+            companySlug: resolvedCompany.slug,
+            companyUid: resolvedCompany.uid,
+            repoPath: cwd,
+            env,
+            nowMs: nowFn().getTime(),
+        });
+        if (refined.action === "bind") {
+            if (refined.projectId !== projectId)
+                taskId = undefined;
+            projectId = refined.projectId;
+            projectBindReason = refined.reason;
+            diagnostics.push(`project bind: ${refined.reason}`);
+        }
+        else if (refined.action === "create") {
+            projectBindReason = refined.reason;
+            if (!deps.offline && resolvedCompany.uid && deps.ensureProjectBoard) {
+                try {
+                    await deps.ensureProjectBoard({
+                        companyUid: resolvedCompany.uid,
+                        projectId,
+                        prdPath: refined.prdPath,
+                    });
+                    diagnostics.push(`project board created for ${projectId}`);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    diagnostics.push(`project board create failed: ${message}`);
+                    projectBindReason = `Board create failed for ${projectId}: ${message}`;
+                    projectCandidates = [{ projectId, title: projectId }];
+                    projectGate = "choose";
+                    projectId = undefined;
+                    taskId = undefined;
+                    projectResolved = null;
+                }
+            }
+            else {
+                diagnostics.push(`project bind: local PRD for ${projectId}; Board create waits for online reconcile`);
+            }
+        }
+        else if (refined.action === "ask") {
+            projectBindReason = refined.reason;
+            projectCandidates = refined.candidates;
+            projectGate = "choose";
+            projectId = undefined;
+            taskId = undefined;
+            projectResolved = null;
+            diagnostics.push(`project ask: ${refined.reason}`);
+        }
+    }
+    const bindResultFields = {
+        ...(projectBindReason ? { projectBindReason } : {}),
+        ...(projectCandidates ? { projectCandidates } : {}),
+    };
+    const bindStateFields = {
+        ...bindResultFields,
+        ...(projectGate ? { projectGate } : {}),
+    };
     // Trusted / deterministic auto-bind never asks.
     // Transcript-sourced sessions never ask (US-018).
     const fromTranscript = obs.source === "transcript";
@@ -457,7 +531,10 @@ export async function reconcileObservation(obs, deps) {
         (projectResolved.source === "deterministic_cwd" ||
             projectResolved.source === "deterministic_registry"));
     let classification;
-    if (autoBound) {
+    if (projectGate === "choose") {
+        classification = "needs_project";
+    }
+    else if (autoBound) {
         classification = "bound";
     }
     else if (projectId && taskId) {
@@ -569,6 +646,7 @@ export async function reconcileObservation(obs, deps) {
             ...(typeof toolWrites === "number" ? { toolWrites } : {}),
             ...(hasTurn ? { hasTurn: true } : {}),
             ...(decision ? { decision } : {}),
+            ...bindStateFields,
             ...transcriptFields,
         }, prior), deps.root);
         const kind = registerClassification === "bound"
@@ -591,6 +669,7 @@ export async function reconcileObservation(obs, deps) {
                 projectId,
                 taskId,
                 bindingEpisodeId: acknowledgedPrior.bindingEpisodeId,
+                ...bindResultFields,
             }),
             exitCode: EXIT_OK,
             diagnostics,
@@ -652,6 +731,7 @@ export async function reconcileObservation(obs, deps) {
             ...(hasTurn ? { hasTurn: true } : {}),
             ...(decision ? { decision } : {}),
             ...(companyConfidence ? { companyConfidence } : {}),
+            ...bindStateFields,
             ...transcriptFields,
         }, prior);
         statePath = writeSessionState(stateWrite, deps.root);
@@ -690,6 +770,7 @@ export async function reconcileObservation(obs, deps) {
                 companySlug: resolvedCompany.slug,
                 projectId,
                 taskId,
+                ...bindResultFields,
             }),
             exitCode: EXIT_OK,
             diagnostics: [...diagnostics, "offline/local: operation remains queued"],
@@ -736,6 +817,7 @@ export async function reconcileObservation(obs, deps) {
                 startedAt,
                 ...(typeof toolWrites === "number" ? { toolWrites } : {}),
                 ...(hasTurn ? { hasTurn: true } : {}),
+                ...bindStateFields,
                 ...transcriptFields,
             }, 
             // Merge against the just-written projection rather than the stale
@@ -761,6 +843,7 @@ export async function reconcileObservation(obs, deps) {
                 projectId,
                 taskId,
                 bindingEpisodeId: delivered.receiptId,
+                ...bindResultFields,
             }),
             exitCode: EXIT_OK,
             diagnostics: [...diagnostics, `acked receipt=${delivered.receiptId}`],
@@ -781,6 +864,7 @@ export async function reconcileObservation(obs, deps) {
                 projectId,
                 taskId,
                 errorCode: delivered.code,
+                ...bindResultFields,
             }),
             exitCode: EXIT_OK,
             diagnostics: [...diagnostics, `transient ${delivered.code}; remains queued`],
@@ -801,6 +885,7 @@ export async function reconcileObservation(obs, deps) {
             projectId,
             taskId,
             errorCode: delivered.code,
+            ...bindResultFields,
         }),
         exitCode: EXIT_OK,
         diagnostics: [...diagnostics, `quarantined: ${delivered.code}`],

package/dist/lib/work-context/state.d.ts

@@ -91,6 +91,19 @@ export interface SessionStateFile {
     transcriptMarker?: "from transcript";
     /** Historical repair under device-default evidence is intentionally weak. */
     companyConfidence?: "device_default";
+    /** Why the current project was chosen, or why the session is asking. */
+    projectBindReason?: string;
+    /** Ranked alternatives when the session is waiting for a project choice. */
+    projectCandidates?: Array<{
+        projectId: string;
+        title?: string;
+        score?: number;
+    }>;
+    /**
+     * When set, flush holds events instead of posting them.
+     * `choose` — the match was unclear. `missing_board` — the server 404'd the project.
+     */
+    projectGate?: "choose" | "missing_board";
     updatedAt: string;
 }
 /**

package/dist/lib/work-context/state.js

@@ -29,6 +29,9 @@ export const SESSION_STATE_ALLOWLIST = new Set([
     "localHarness",
     "transcriptMarker",
     "companyConfidence",
+    "projectBindReason",
+    "projectCandidates",
+    "projectGate",
     "updatedAt",
 ]);
 const SESSION_STATE_LOCK_TIMEOUT_MS = 5_000;
@@ -228,6 +231,12 @@ export function projectSessionState(state) {
         out.transcriptMarker = state.transcriptMarker;
     if (state.companyConfidence)
         out.companyConfidence = state.companyConfidence;
+    if (state.projectBindReason)
+        out.projectBindReason = state.projectBindReason;
+    if (state.projectCandidates?.length)
+        out.projectCandidates = state.projectCandidates;
+    if (state.projectGate)
+        out.projectGate = state.projectGate;
     return out;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.138.0",
+  "version": "5.140.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {