@orchestrator-claude/definitions 3.32.1 → 3.33.0

package/hooks/session-start.ts

@@ -14,6 +14,12 @@ import {
   getNextAction,
   outputContext,
   getToken,
+  allocateSessionNumber,
+  resolveHookProjectRoot,
+  getEffectiveProjectId,
+  setEffectiveProjectId,
+  listRegisteredProjects,
+  type AllocateSessionResult,
 } from './lib/api-client.js';
 import {
   needsRescan,
@@ -26,26 +32,45 @@ import {
   filterRelevantMemories,
   formatMemoryContext,
 } from './lib/capability-scanner.js';
+import { readSessionSelection } from './lib/session-selection.js';
 
 const HOOK = 'SESSION-START';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const GRAPHRAG_TIMEOUT_MS = 2000;
-const PROJECT_ROOT = join(__dirname, '..', '..');
+// RFC-040 Operator Multi-Project — Slice 5 (C5), S358/S361: cwd-aware
+// resolution (walks up for the .orchestrator sentinel) replaces the
+// __dirname-hardcoded path. `null` means an unregistered cwd — deliberately
+// NO __dirname fallback (would leak the Orchestrator's own vault into an
+// unregistered project). All PROJECT_ROOT-derived paths below degrade to
+// `null` and their consumers skip gracefully (AC-C5-2).
+const PROJECT_ROOT = resolveHookProjectRoot(process.cwd());
+// RFC-040 Operator Multi-Project — Slice 2C (C9), S358, TASK-C9-03
+const PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID ?? '';
 
 // ─── Capability Matrix paths (RFC-027 Sprint 2) ─────────
 const HOME = process.env.HOME ?? process.env.USERPROFILE ?? '/home/user';
 const INSTALLED_PLUGINS_PATH = join(HOME, '.claude', 'plugins', 'installed_plugins.json');
-const AGENTS_DIR = join(PROJECT_ROOT, '.claude', 'agents');
-const VAULT_CONFIG_PATH = join(PROJECT_ROOT, 'project-guidelines', '.vault-config.yaml');
-const PROFILES_PATH = join(PROJECT_ROOT, '.claude', 'plugin-profiles.yaml');
-const MEMORY_INDEX_PATH = join(
-  PROJECT_ROOT,
-  '.claude',
-  'agent-memory',
-  'orchestrator',
-  'memory-index.yaml'
-);
+
+// ─── 2-Phase Selection (RFC-040 TD-204 ⑤-C) ─────────────────────────────
+// Feature-flagged, default OFF — the kill-switch for the whole phase-1
+// prompt + persisted-selection-read path. With the flag unset/false,
+// `selection` stays permanently undefined (byte-for-byte the pre-⑤-C
+// single-phase behaviour tested by session-start-project-binding.test.ts).
+const PROJECT_SELECTION_ENABLED = process.env.ORCHESTRATOR_ENABLE_PROJECT_SELECTION === 'true';
+// Deliberately NOT under ~/.claude (TD-204 hazard boundary — this hook
+// never reads/writes that tree) and NOT under PROJECT_ROOT (a selection
+// must be persistable even when cwd has no .orchestrator sentinel yet —
+// that is exactly the "no binding" state phase-1 prompts for).
+const SESSION_SELECTION_STATE_DIR = join(HOME, '.orchestrator', 'session-selection');
+const AGENTS_DIR = PROJECT_ROOT ? join(PROJECT_ROOT, '.claude', 'agents') : null;
+const VAULT_CONFIG_PATH = PROJECT_ROOT
+  ? join(PROJECT_ROOT, 'project-guidelines', '.vault-config.yaml')
+  : null;
+const PROFILES_PATH = PROJECT_ROOT ? join(PROJECT_ROOT, '.claude', 'plugin-profiles.yaml') : null;
+const MEMORY_INDEX_PATH = PROJECT_ROOT
+  ? join(PROJECT_ROOT, '.claude', 'agent-memory', 'orchestrator', 'memory-index.yaml')
+  : null;
 
 /**
  * Read session_id from SessionStart stdin payload.
@@ -64,7 +89,9 @@ function readSessionId(): string | null {
 
 // ─── RFC-033 Phase 1: project-state.yaml reader ─────────────────────────────
 
-const PROJECT_STATE_PATH = join(PROJECT_ROOT, 'project-guidelines', 'project-state.yaml');
+const PROJECT_STATE_PATH = PROJECT_ROOT
+  ? join(PROJECT_ROOT, 'project-guidelines', 'project-state.yaml')
+  : null;
 
 interface PendingCounts {
   critical: number;
@@ -136,6 +163,11 @@ export function readProjectState(filePath: string): BacklogSummary | null {
  */
 function readBacklogFallback(): BacklogSummary {
   try {
+    if (PROJECT_ROOT === null) {
+      throw new Error(
+        'PROJECT_ROOT unresolved (unregistered cwd) — no .orchestrator sentinel found'
+      );
+    }
     const backlogPath = join(PROJECT_ROOT, 'project-guidelines', 'BACKLOG.md');
     const content = readFileSync(backlogPath, 'utf-8');
     const allLines = content.split('\n');
@@ -195,13 +227,15 @@ function readBacklogFallback(): BacklogSummary {
  * Return shape is IDENTICAL to the original function.
  */
 function getBacklogSummary(): BacklogSummary {
-  const structured = readProjectState(PROJECT_STATE_PATH);
-  if (structured !== null) {
-    log(
-      HOOK,
-      `project-state.yaml: version=${structured.version} next=${structured.next.slice(0, 50)}`
-    );
-    return structured;
+  if (PROJECT_STATE_PATH !== null) {
+    const structured = readProjectState(PROJECT_STATE_PATH);
+    if (structured !== null) {
+      log(
+        HOOK,
+        `project-state.yaml: version=${structured.version} next=${structured.next.slice(0, 50)}`
+      );
+      return structured;
+    }
   }
   log(HOOK, 'project-state.yaml absent/invalid — using BACKLOG.md fallback');
   return readBacklogFallback();
@@ -216,6 +250,11 @@ type TierInfo = { onboardingNeeded: true } | { tier: number; source: string } |
  */
 async function checkTier(): Promise<TierInfo> {
   try {
+    // RFC-040 C5: unregistered cwd — no vault to check tier against, skip.
+    if (VAULT_CONFIG_PATH === null) {
+      log(HOOK, 'checkTier: PROJECT_ROOT unresolved (unregistered cwd) — skipping tier check');
+      return null;
+    }
     // Use module-level VAULT_CONFIG_PATH constant (IMP-003)
     if (!existsSync(VAULT_CONFIG_PATH)) {
       return { onboardingNeeded: true };
@@ -245,12 +284,138 @@ export function formatTierSegment(info: TierInfo): string {
   return ` | tier=${info.tier} (${info.source})`;
 }
 
+/**
+ * Format the result of allocateSessionNumber() as a segment string for the
+ * ORCHESTRATOR-DATA line. Fail-open: returns "" when allocation failed
+ * (API down, no token, non-2xx) — RFC-040 Operator Multi-Project, Slice 2C
+ * (C9), S358, TASK-C9-03.
+ */
+export function formatSessionNumberSegment(result: AllocateSessionResult | null): string {
+  if (result === null) return '';
+  return ` | session_number=${result.number}`;
+}
+
+// ─── Session Project Binding Precedence (RFC-040 TD-204 §⑥-c) ──────────────
+// Slice 5 (C5) resolves a project ROOT for filesystem access
+// (resolveHookProjectRoot(cwd), walk-up for the .orchestrator sentinel).
+// This primitive instead resolves the project IDENTITY (projectId) a
+// session is BOUND to, applying a strict first-match precedence:
+//   1. env-override (ORCHESTRATOR_PROJECT_ID) — an IMMUTABLE pin. If set,
+//      the session is DEFINITIVELY that project; no other signal may
+//      override it.
+//   2. explicit selection — forward-compat for Slice 5-C (⑤-C, NOT YET
+//      IMPLEMENTED). `selection` is always undefined until ⑤-C lands, so
+//      this tier is dormant-but-tested (mirrors the dormant-but-tested
+//      branches of decideWorkflowGuardAction in workflow-guard.ts, TD-204
+//      ⑤-A).
+//   3. cwd-hint — the project resolved lazily from cwd via
+//      ensureProjectIdResolved/getEffectiveProjectId() (RFC-040 C5/C9).
+//   4. none — no signal available; caller must force selection/registration.
+// The `pinned` flag drives formatProjectBindingSegment's hard surfacing
+// requirement below: an env-override pin is NEVER a silent surprise.
+
+export type SessionProjectBindingSource = 'env-override' | 'selection' | 'cwd-hint' | 'none';
+
+export interface SessionProjectBinding {
+  projectId: string;
+  source: SessionProjectBindingSource;
+  pinned: boolean;
+}
+
+export interface SessionProjectBindingInput {
+  envOverride: string;
+  /** Explicit project selection (RFC-040 Slice 5-C, ⑤-C — NOT YET IMPLEMENTED). Always undefined until ⑤-C lands. */
+  selection?: string;
+  cwdHintProjectId: string;
+}
+
+/**
+ * Pure precedence resolver for session project binding (RFC-040 TD-204
+ * ⑥-c). Zero fs/API calls — takes only injected inputs, so every tier
+ * (including the dormant `selection` tier) is independently testable.
+ */
+export function resolveSessionProjectBinding(
+  input: SessionProjectBindingInput
+): SessionProjectBinding {
+  const { envOverride, selection, cwdHintProjectId } = input;
+
+  if (envOverride) {
+    return { projectId: envOverride, source: 'env-override', pinned: true };
+  }
+  if (selection) {
+    return { projectId: selection, source: 'selection', pinned: false };
+  }
+  if (cwdHintProjectId) {
+    return { projectId: cwdHintProjectId, source: 'cwd-hint', pinned: false };
+  }
+  return { projectId: '', source: 'none', pinned: false };
+}
+
+/**
+ * Formats a SessionProjectBinding as an ADDITIVE segment for the
+ * [ORCHESTRATOR-DATA] line (RFC-040 TD-204 ⑥-c). Hard requirement: when
+ * `pinned` (env-override), the pin MUST be surfaced explicitly — zero
+ * silent surprise.
+ */
+export function formatProjectBindingSegment(binding: SessionProjectBinding): string {
+  if (binding.source === 'none') return ' | project=none';
+  if (binding.pinned) return ` | project=${binding.projectId} (pinned via env-override)`;
+  return ` | project=${binding.projectId} (${binding.source})`;
+}
+
+/**
+ * Phase 1 of the 2-phase selection flow (RFC-040 TD-204 ⑤-C, feature-
+ * flagged): builds the [ORCHESTRATOR-PROJECT-SELECTION] prompt emitted
+ * when NO binding resolved (env unset, no persisted selection, cwd
+ * unregistered). Instructs the assistant to ask (AskUserQuestion) which
+ * registered project this session belongs to, listing every registered
+ * project by name/id/rootPath.
+ *
+ * Fail-open (Class C benign degrade, mirrors buildCapabilityMatrixContext
+ * / getGraphContext): returns "" on any error — a failed project-list
+ * fetch must never block or crash the hook.
+ */
+export async function buildProjectSelectionPrompt(): Promise<string> {
+  try {
+    const projects = await listRegisteredProjects();
+
+    if (projects.length === 0) {
+      return [
+        '[ORCHESTRATOR-PROJECT-SELECTION] No project is bound to this session (env unset, cwd unregistered, no prior selection) and no projects are registered yet.',
+        '[ORCHESTRATOR] Ask the user (AskUserQuestion) whether to register this cwd as a new project, or proceed unmanaged for this session.',
+      ].join('\n');
+    }
+
+    const options = projects.map((p) => `${p.name} (${p.id}) — ${p.rootPath}`).join('; ');
+    return [
+      '[ORCHESTRATOR-PROJECT-SELECTION] No project is bound to this session (env unset, cwd unregistered, no prior selection).',
+      `[ORCHESTRATOR] Ask the user (AskUserQuestion) which project this session belongs to. Registered projects: ${options}`,
+    ].join('\n');
+  } catch (err) {
+    log(HOOK, `buildProjectSelectionPrompt failed: ${String(err)}`);
+    return '';
+  }
+}
+
 /**
  * Build [CAPABILITY-MATRIX] + [MEMORY-CONTEXT] lines for injection.
  * Fail-open: returns empty string on any error.
  */
 function buildCapabilityMatrixContext(): string {
   try {
+    // RFC-040 C5: unregistered cwd — no vault/agents/memory-index to read, skip.
+    if (
+      VAULT_CONFIG_PATH === null ||
+      AGENTS_DIR === null ||
+      PROFILES_PATH === null ||
+      MEMORY_INDEX_PATH === null
+    ) {
+      log(
+        HOOK,
+        'buildCapabilityMatrixContext: PROJECT_ROOT unresolved (unregistered cwd) — skipping'
+      );
+      return '';
+    }
     let index = readCapabilitiesFromVault(VAULT_CONFIG_PATH);
     const cachedMtime = index?.installedPluginsMtime ?? '';
 
@@ -402,6 +567,13 @@ export async function getGraphContext(
 async function main(): Promise<void> {
   log(HOOK, 'SessionStart hook triggered');
 
+  if (PROJECT_ROOT === null) {
+    log(
+      HOOK,
+      'PROJECT_ROOT unresolved: cwd has no .orchestrator sentinel up to the filesystem root — vault-dependent sections (tier, capability matrix, BACKLOG fallback) will be skipped this session (RFC-040 C5, AC-C5-2).'
+    );
+  }
+
   const sessionId = readSessionId();
   const sessionSegment = sessionId ? ` | session=${sessionId}` : '';
   if (sessionId) log(HOOK, `Claude session: ${sessionId}`);
@@ -410,21 +582,88 @@ async function main(): Promise<void> {
   const tierInfo = await checkTier();
   const tierSegment = formatTierSegment(tierInfo);
   const capabilityContext = buildCapabilityMatrixContext();
-  const workflow = await getActiveWorkflow();
 
   // Sprint inbox check (RFC-027 S4 — only for sprint panes)
   const sprintInboxContext = checkSprintInbox();
 
-  // Graph context (RFC-021 T-G4-06) — fail-open, 2s timeout
+  // Graph context (RFC-021 T-G4-06) — fail-open, 2s timeout. RFC-040 TD-206
+  // (S372): this getToken() call MUST stay HERE, before
+  // resolveSessionProjectBinding() below — it is what bootstraps the
+  // cwd-hint tier (getToken -> ensureProjectIdResolved ->
+  // getEffectiveProjectId() reads the resolved value just below). Moving
+  // getActiveWorkflow()/getNextAction() later (see below) must not remove
+  // this bootstrap, or the cwd-hint tier would regress to reading '' .
   const token = await getToken();
   const graphContext = await getGraphContext(token);
 
+  // RFC-040 TD-204 ⑤-C: read a previously-persisted selection for THIS
+  // sessionId — feature-flagged (default OFF, kill-switch). With the flag
+  // off, `selection` stays undefined and the tier is permanently dormant,
+  // exactly as before ⑤-C (byte-for-byte pre-existing single-phase
+  // behaviour). readSessionSelection is Class C benign-degrade — never
+  // throws, so no try/catch needed here.
+  const selection =
+    PROJECT_SELECTION_ENABLED && sessionId
+      ? readSessionSelection(SESSION_SELECTION_STATE_DIR, sessionId)
+      : undefined;
+
+  // RFC-040 TD-204 ⑥-c: resolve the session's project binding via strict
+  // precedence (env-override pin > selection [⑤-C, feature-flagged] >
+  // cwd-hint > none) — centralizes what used to be the inline `PROJECT_ID
+  // || getEffectiveProjectId()` fallback into a single, pure, testable
+  // source of truth, and drives the mandatory pin-surfacing segment below.
+  const projectBinding = resolveSessionProjectBinding({
+    envOverride: PROJECT_ID,
+    selection,
+    cwdHintProjectId: getEffectiveProjectId(),
+  });
+  const projectBindingSegment = formatProjectBindingSegment(projectBinding);
+
+  // RFC-040 TD-206 (S372): feed the precedence-resolved binding back into
+  // the api-client's internal scoping so getActiveWorkflow()/getNextAction()
+  // (moved below, AFTER this point — see comment there) query under the
+  // SAME projectId the [ORCHESTRATOR-DATA] line above surfaces, instead of
+  // whatever cwd-hint ensureProjectIdResolved happened to resolve during the
+  // getToken() bootstrap call above. Closes the S371 Case-2 gap (selection
+  // displayed correctly but workflow queried under the cwd project).
+  // Safe no-op when source is 'env-override' (binding.projectId already
+  // equals api-client's own PROJECT_ID, seeded from the same
+  // ORCHESTRATOR_PROJECT_ID env var at import time) or 'cwd-hint'
+  // (binding.projectId already equals getEffectiveProjectId()).
+  setEffectiveProjectId(projectBinding.projectId);
+
+  // RFC-040 TD-204 ⑤-C, phase 1: when NO binding resolved at all AND the
+  // flag is on, prompt the operator to select a project. Computed ONCE and
+  // folded as extra lines into whichever outputContext() call below fires
+  // — never a SECOND outputContext call, so exactly one [ORCHESTRATOR-DATA]
+  // block is ever emitted (double-load regression guard).
+  const projectSelectionPrompt =
+    PROJECT_SELECTION_ENABLED && projectBinding.source === 'none'
+      ? await buildProjectSelectionPrompt()
+      : '';
+
+  // RFC-040 Operator Multi-Project — Slice 2C (C9), S358, TASK-C9-03: allocate
+  // a globally-numbered session (fail-open — API down never blocks the hook).
+  // RFC-040 Slice 5 (C5), S358/S361 / ⑥-c: allocation receives
+  // projectBinding.projectId — the same precedence-resolved id surfaced in
+  // the ORCHESTRATOR-DATA line below (AC-C5-4, single source of truth).
+  const sessionAllocation = await allocateSessionNumber(projectBinding.projectId);
+  const sessionNumberSegment = formatSessionNumberSegment(sessionAllocation);
+
+  // RFC-040 TD-206 (S372): getActiveWorkflow() now runs AFTER
+  // setEffectiveProjectId() above (moved from its original position, which
+  // ran BEFORE binding resolution — session-start.ts:584 pre-TD-206), so
+  // its X-Project-ID header carries the precedence-resolved
+  // binding.projectId (selection winner when present), not the raw
+  // cwd-resolved value it used to see (S371 Case-2 finding).
+  const workflow = await getActiveWorkflow();
+
   if (!workflow) {
     log(HOOK, 'No active workflow, injecting greeting data');
     outputContext(
       'SessionStart',
       [
-        `[ORCHESTRATOR-DATA] version=${backlog.version}${sessionSegment} | workflow=none${tierSegment} | next=${backlog.next}`,
+        `[ORCHESTRATOR-DATA] version=${backlog.version}${sessionSegment} | workflow=none${tierSegment}${sessionNumberSegment}${projectBindingSegment} | next=${backlog.next}`,
         backlog.lastSession ? `[LAST-SESSION] ${backlog.lastSession}` : '',
         backlog.status ? `[PENDENTE] ${backlog.status}` : '',
         `[ORCHESTRATOR] Greet the user via AskUserQuestion using the data above (CLAUDE.md Rule #1).`,
@@ -433,6 +672,7 @@ async function main(): Promise<void> {
         capabilityContext,
         graphContext,
         sprintInboxContext,
+        projectSelectionPrompt,
       ]
         .filter(Boolean)
         .join('\n')
@@ -451,12 +691,13 @@ async function main(): Promise<void> {
   outputContext(
     'SessionStart',
     [
-      `[ORCHESTRATOR-DATA] version=${backlog.version}${sessionSegment} | workflow=${workflow.id} | type=${workflow.type} | phase=${workflow.currentPhase} | status=${workflow.status}${actionHint}${tierSegment}`,
+      `[ORCHESTRATOR-DATA] version=${backlog.version}${sessionSegment} | workflow=${workflow.id} | type=${workflow.type} | phase=${workflow.currentPhase} | status=${workflow.status}${actionHint}${tierSegment}${sessionNumberSegment}${projectBindingSegment}`,
       `[ORCHESTRATOR] Active workflow detected. Greet the user via AskUserQuestion showing workflow state (CLAUDE.md Rule #1).`,
       'Do NOT invoke /orchestrator skill for the greeting — use AskUserQuestion directly.',
       'Invoke /orchestrator skill when the user chooses to continue the workflow.',
       capabilityContext,
       graphContext,
+      projectSelectionPrompt,
     ]
       .filter(Boolean)
       .join('\n')

package/hooks/sprint-registry.mjs

@@ -0,0 +1,59 @@
+import { createRequire as __createRequireShim } from 'node:module'; const require = __createRequireShim(import.meta.url);
+
+// hooks/sprint-registry.ts
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+function log(msg) {
+  process.stderr.write(`[sprint-registry] ${msg}
+`);
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+async function main() {
+  const stdin = await readStdin();
+  const sessionId = stdin.session_id ?? void 0;
+  const sprintId = process.env.SPRINT_ID;
+  const paneRole = process.env.PANE_ROLE;
+  if (!sprintId || !paneRole) {
+    log(`Skipping: SPRINT_ID=${sprintId ?? "unset"} PANE_ROLE=${paneRole ?? "unset"}`);
+    process.exit(0);
+  }
+  const registryDir = `/tmp/${sprintId}/registry`;
+  const entryPath = join(registryDir, `${paneRole}.json`);
+  const workflowId = process.env.WORKFLOW_ID;
+  const entry = {
+    role: paneRole,
+    sprintId,
+    pid: process.pid,
+    registeredAt: (/* @__PURE__ */ new Date()).toISOString(),
+    worktreePath: process.cwd()
+  };
+  if (sessionId) {
+    entry.sessionId = sessionId;
+  }
+  if (workflowId) {
+    entry.workflowId = workflowId;
+  }
+  try {
+    mkdirSync(registryDir, { recursive: true });
+    writeFileSync(entryPath, JSON.stringify(entry, null, 2), "utf-8");
+    log(
+      `Registered ${paneRole} for sprint ${sprintId} (pid=${process.pid}, session=${sessionId ?? "unknown"})`
+    );
+  } catch (err) {
+    log(`Registration failed: ${err}`);
+  }
+  process.exit(0);
+}
+main().catch(() => process.exit(0));