usesteady 0.1.0-alpha.1

package/dist/src/understand/silent-guidance/selector.js

@@ -0,0 +1,158 @@
+/**
+ * Silent Guidance Mode Selector.
+ *
+ * Inspects the raw input for shape-level signals and returns the most
+ * appropriate guidance template mode.
+ *
+ * ── Contracts ────────────────────────────────────────────────────────────────
+ *
+ *   1. Only called when bridgeSilenceReason === "no_interpreter_claimed".
+ *   2. Deterministic: same input → same mode, always.
+ *   3. Returns a mode — never null. "unknown" is the safe fallback.
+ *   4. Does NOT classify intent. Does NOT produce category/confidence.
+ *   5. Does NOT guess tools, services, file paths, or values.
+ *   6. Does NOT affect mode, signal, intentState, or any decision.
+ *   7. Regex match priority: investigation → operation → content_iteration → unknown.
+ *      First match wins. This ordering prevents cross-domain false positives.
+ *
+ * ── Pattern philosophy ────────────────────────────────────────────────────────
+ *
+ *   Patterns are narrow, not broad.  Better to fall through to "unknown"
+ *   (which still shows improved guidance over the old code-patch default)
+ *   than to claim a mode incorrectly.
+ *
+ *   Each pattern targets high-signal, low-ambiguity tokens:
+ *   - "debug" is always QA; "deploy" is always ops; "tagline" is always content.
+ *   - Ambiguous terms like "improve", "fix", "check" are deliberately excluded
+ *     unless combined with a domain-specific qualifier.
+ */
+// ── Pattern sets ───────────────────────────────────────────────────────────────
+/**
+ * QA, debugging, bug reproduction, smoke testing, mocking.
+ * Also covers analytical investigation verbs: analyze, monitor, verify.
+ * Extended with diagnostic verbs: inspect, trace, diagnose, troubleshoot.
+ *
+ * ── Expansion (Sessions 4–5) ──────────────────────────────────────────────────
+ *
+ *   Added analyz\w+ (analyze, analyzes, analyzing, analysing — any stem form).
+ *   Added monitor: "monitor the error rate" → investigation, not ops.
+ *   Added verify:  "verify the deployment health" → investigation.
+ *
+ *   These cleared C1 (≥ 2 cross-persona recurrences) and C3 (clear category)
+ *   in Session 5 before being added. C2 still fails — interpreter remains NO-GO.
+ *
+ *   Priority: investigation runs before operation. When "monitor the ingestion
+ *   pipeline" is tested, `monitor\b` fires here instead of `pipeline\b` in
+ *   OPERATION_RE. That is the correct outcome.
+ *
+ * ── Expansion (Session 6) ─────────────────────────────────────────────────────
+ *
+ *   Added inspect:        3/3 recurrences across 3 personas (Dan, Syd, Pat).
+ *   Added trac(?:e|ing):  "trace the query" / "tracing the call" — investigation.
+ *   Added diagnos\w+:     diagnose, diagnosing, diagnosis, diagnostic.
+ *                         4 cross-persona recurrences (Syd, Pat, Donna, Maya).
+ *   Added troubleshoot\w*: troubleshoot, troubleshooting.
+ *                          1 occurrence in Session 6 (Syd), eligible by C3 alone;
+ *                          diagnose+troubleshoot share semantic class, so combined
+ *                          C1 passes. Both fail C2 — no interpreter candidate.
+ *
+ *   Note on "debug": debug is already in this pattern (added in v1). After the
+ *   Session 6 config_change fix (removing bare "debug" from CONFIG_NOUNS_RE),
+ *   "debug the X" inputs are now bridge-silent and correctly route here.
+ *   No change to the debug token was needed.
+ */
+const INVESTIGATION_RE = /\b(?:debug|bug|repro(?:duce)?|flak[iy]|smoke[\s-]test|mock(?:ing)?|test\s+(?:coverage|fixtures?|cases?)|coverage\s+report(?:ing)?|analyz\w+|monitor|verify|inspect|trac(?:e|ing)|diagnos\w+|troubleshoot\w*)\b/i;
+/**
+ * Infrastructure ops, deployments, pipelines, schema changes, migrations.
+ * Also covers export, sync, scale (extended nouns), launch, roll-out.
+ *
+ * ── Expansion (Sessions 4–5) ──────────────────────────────────────────────────
+ *
+ *   scale — extended to cover workers, fleet, replicas, pods, instances, nodes.
+ *     Previously only matched service/app/cluster; Sessions 4–5 confirmed the
+ *     broader noun set recurs across DevOps and SRE personas.
+ *
+ *   export\b — standalone is sufficient; context is always data/artifact movement.
+ *     4 cross-persona recurrences (Sam, Nia, Fay, Kai) cleared C1+C3.
+ *
+ *   sync\b  — data/state synchronisation; 2 cross-persona recurrences (Leo, Kai).
+ *
+ *   launch\b + roll[\s-]out\b — product/feature deployment verbs.
+ *     'deploy' was already covered; 'launch' and 'roll-out' were not.
+ *     Note: 'launch the new feature' previously false-fired config_change via
+ *     the 'feature' noun. That noun was removed from CONFIG_NOUNS_RE (see
+ *     config-intent.interpreter.ts). Adding 'launch\b' here is now safe.
+ *
+ * ── Expansion (Session 7 — CRM/ticket vocabulary) ─────────────────────────────
+ *
+ *   Evidence gate results (Session 7 report):
+ *     suspend    C1 ✓ (4 personas)  C2 ✓ (non-execute)  C3 → ops
+ *     assign     C1 ✓ (4 personas)  C2 ✓                C3 → ops
+ *     escalate   C1 ✓ (4 personas)  C2 ✓                C3 → ops
+ *     merge      C1 ✓ (3 personas)  C2 ✓                C3 → ops
+ *     lock       C1 ✓ (2 personas)  C2 ✓                C3 → ops
+ *
+ *   Patterns added:
+ *     suspend\b      — account / user / service suspension
+ *     assign\b       — ticket / case assignment
+ *     escalat\w+     — escalate, escalating, escalation
+ *     merge\b        — ticket, case, account, or record merge
+ *     lock\b         — account / ticket lock
+ *
+ * ── Expansion (Session 7 — Ops lifecycle vocabulary) ──────────────────────────
+ *
+ *   Evidence gate results (Session 7 report):
+ *     rotate    C1 ✓ (4 personas)  C2 ✓  C3 → ops
+ *     upgrade   C1 ✓ (4 personas)  C2 ✓  C3 → ops
+ *     provision C1 ✓ (4 personas)  C2 ✓  C3 → ops
+ *     failover  C1 ✓ (3 personas)  C2 ✓  C3 → ops
+ *     patch     C1 ✓ (3 personas)  C2 ✓  C3 → ops
+ *     drain     C1 ✓ (2 personas)  C2 ✓  C3 → ops
+ *
+ *   Patterns added:
+ *     rotat\w+\s+(?:(?:\w[\w-]*)\s+){0,3}(?:keys?|secrets?|credentials?|tokens?|certs?|certificates?|api[\s-]keys?)
+ *       — DELIBERATELY SCOPED to credential/key rotation only.
+ *         Allows up to 3 qualifier words between "rotate" and the credential
+ *         noun so that "rotate the TLS certificates" and "rotate expired API keys"
+ *         both match, while "rotate customer passwords" does not match (passwords
+ *         is not a credential noun in this list — it is a data record noun covered
+ *         by the bulk_data_exfiltration safety detector which runs first).
+ *
+ *     upgrade\b      — service, cluster, dependency upgrade
+ *     provision\w*   — provision, provisioning, provisioned
+ *     failover\b     — explicit, unambiguous
+ *     drain\b        — drain node, drain traffic, drain queue
+ *     patch\b        — ops security/service patch (NOT the structured change command
+ *                      `patch <file> search=…`; that format is consumed by the
+ *                      completion layer before the selector is ever called)
+ */
+const OPERATION_RE = /\b(?:deploy(?:ment)?|rollback|restart|reboot|pipeline|migrat(?:e|ions?)|health[\s-]check|launch|roll[\s-]out|export|sync|add\s+(?:a\s+|an\s+)?(?:column|index)|update\s+the\s+schema|schema\s+change|run\s+(?:the\s+)?(?:pipeline|job|server|service|migrations?)|optimize\s+(?:the\s+)?(?:query|queries|slow\s+query)|scale\s+(?:the\s+)?(?:service|app|cluster|workers?|fleet|replicas?|pods?|instances?|nodes?)|suspend|assign|escalat\w+|merge|lock|rotat\w+\s+(?:(?:\w[\w-]*)\s+){0,3}(?:keys?|secrets?|credentials?|tokens?|certs?|certificates?|api[\s-]keys?)|upgrade|provision\w*|failover|drain|patch)\b/i;
+/**
+ * Copy, UX text, product descriptions, taglines, user flows.
+ * Only high-signal content/product vocabulary — avoids over-matching.
+ */
+const CONTENT_ITERATION_RE = /\b(tagline\b|compelling\b|testimonial(?:s)?\b|onboarding\b|user[\s-]flow\b|checkout[\s-]flow\b|product[\s-]description\b|improve\s+the\s+(?:user|product|content|copy|experience|flow|ux)\b|make\b.{0,25}\bmore\s+(?:compelling|engaging)\b)\b/i;
+// ── Selector ──────────────────────────────────────────────────────────────────
+/**
+ * Select the appropriate silent guidance template mode for a bridge-silent flow.
+ *
+ * Priority (first match wins):
+ *   1. investigation    — QA / debugging signals
+ *   2. operation        — infra / schema / pipeline signals
+ *   3. content_iteration — copy / UX / product signals
+ *   4. unknown          — safe fallback (still better than code-patch default)
+ *
+ * "code_patch" is never returned here; it applies only when an interpreter
+ * already fired (bridgeFired === true), meaning the request is already
+ * enriched and needs no silent mode template.
+ */
+export function selectSilentGuidanceMode(input) {
+    if (INVESTIGATION_RE.test(input))
+        return "investigation";
+    if (OPERATION_RE.test(input))
+        return "operation";
+    if (CONTENT_ITERATION_RE.test(input))
+        return "content_iteration";
+    return "unknown";
+}
+//# sourceMappingURL=selector.js.map

package/dist/src/understand/silent-guidance/selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.js","sourceRoot":"","sources":["../../../../src/understand/silent-guidance/selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,kFAAkF;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,gBAAgB,GACpB,iNAAiN,CAAC;AAEpN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,YAAY,GAChB,qlBAAqlB,CAAC;AAExlB;;;GAGG;AACH,MAAM,oBAAoB,GACxB,iPAAiP,CAAC;AAEpP,iFAAiF;AAEjF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAa;IACpD,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,eAAe,CAAC;IACzD,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;QAAM,OAAO,WAAW,CAAC;IACrD,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,mBAAmB,CAAC;IACjE,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/src/understand/silent-guidance/templates.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Silent Guidance Templates.
+ *
+ * Maps each SilentGuidanceMode to a set of generic, domain-appropriate
+ * CompletionNextStep entries.  These replace the code-patch default
+ * for bridge-silent flows.
+ *
+ * ── Template contracts ────────────────────────────────────────────────────────
+ *
+ *   - Every template has exactly 3 steps (read_first, use_exact_format,
+ *     add_missing_field) — the same structural shape as the code-patch default.
+ *   - No template invents specifics (file names, tool names, table names, etc.).
+ *   - No template implies executability.  All remain in guide mode territory.
+ *   - Templates use angle-bracket placeholders for values the user must supply.
+ *
+ * ── Why 3 steps ──────────────────────────────────────────────────────────────
+ *
+ *   read_first       — orients the user: gather information before acting
+ *   use_exact_format — shows the deterministic format to express the change
+ *   add_missing_field — names what the user must provide to make it actionable
+ */
+import type { CompletionNextStep } from "../completion/types.js";
+import type { SilentGuidanceMode } from "./types.js";
+/**
+ * Return the generic next-step template for a given silent guidance mode.
+ *
+ * Returns a read-only array with exactly 3 steps.
+ * The array is a module-level constant — no allocation on each call.
+ */
+export declare function getSilentGuidanceSteps(mode: SilentGuidanceMode): readonly CompletionNextStep[];
+//# sourceMappingURL=templates.d.ts.map

package/dist/src/understand/silent-guidance/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../../src/understand/silent-guidance/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAiFrD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,kBAAkB,GACvB,SAAS,kBAAkB,EAAE,CAQ/B"}

package/dist/src/understand/silent-guidance/templates.js

@@ -0,0 +1,109 @@
+/**
+ * Silent Guidance Templates.
+ *
+ * Maps each SilentGuidanceMode to a set of generic, domain-appropriate
+ * CompletionNextStep entries.  These replace the code-patch default
+ * for bridge-silent flows.
+ *
+ * ── Template contracts ────────────────────────────────────────────────────────
+ *
+ *   - Every template has exactly 3 steps (read_first, use_exact_format,
+ *     add_missing_field) — the same structural shape as the code-patch default.
+ *   - No template invents specifics (file names, tool names, table names, etc.).
+ *   - No template implies executability.  All remain in guide mode territory.
+ *   - Templates use angle-bracket placeholders for values the user must supply.
+ *
+ * ── Why 3 steps ──────────────────────────────────────────────────────────────
+ *
+ *   read_first       — orients the user: gather information before acting
+ *   use_exact_format — shows the deterministic format to express the change
+ *   add_missing_field — names what the user must provide to make it actionable
+ */
+// ── Templates ──────────────────────────────────────────────────────────────────
+const INVESTIGATION_STEPS = [
+    {
+        type: "read_first",
+        label: "Identify where the issue occurs and gather observable evidence before making any change.",
+    },
+    {
+        type: "use_exact_format",
+        label: 'Read the relevant file or test once you have identified the target: read "<file>"',
+    },
+    {
+        type: "add_missing_field",
+        label: "Provide the exact symptom, test name, or failure condition so the change can be targeted.",
+    },
+];
+const OPERATION_STEPS = [
+    {
+        type: "read_first",
+        label: "Identify the specific tool, service, or system this operation applies to.",
+    },
+    {
+        type: "use_exact_format",
+        label: 'Locate the exact command, config, query, or migration needed: read "<config-or-migration-file>"',
+    },
+    {
+        type: "add_missing_field",
+        label: "Specify what it acts on (service name, table, environment) and what the expected outcome is.",
+    },
+];
+const CONTENT_ITERATION_STEPS = [
+    {
+        type: "read_first",
+        label: 'Read the file containing the current text or content element: read "<file>"',
+    },
+    {
+        type: "use_exact_format",
+        label: 'Apply the change using the exact format: replace "<current text>" with "<new text>" in "<file>"',
+    },
+    {
+        type: "add_missing_field",
+        label: "Provide the specific new wording or content you want to use.",
+    },
+];
+const CODE_PATCH_STEPS = [
+    {
+        type: "read_first",
+        label: 'Read the relevant file first: read "<file>"',
+    },
+    {
+        type: "use_exact_format",
+        label: 'Apply the change: replace "<old>" with "<new>" in "<file>"',
+    },
+    {
+        type: "add_missing_field",
+        label: "Specify the exact file path, old value, and new value.",
+    },
+];
+const UNKNOWN_STEPS = [
+    {
+        type: "read_first",
+        label: "Break this request into one specific, deterministic change before proceeding.",
+    },
+    {
+        type: "use_exact_format",
+        label: 'Use one of these exact formats: read "<file>" | replace "<old>" with "<new>" in "<file>" | commit "<message>"',
+    },
+    {
+        type: "add_missing_field",
+        label: "Specify the exact file, value, or target this request applies to.",
+    },
+];
+// ── Lookup ──────────────────────────────────────────────────────────────────────
+/**
+ * Return the generic next-step template for a given silent guidance mode.
+ *
+ * Returns a read-only array with exactly 3 steps.
+ * The array is a module-level constant — no allocation on each call.
+ */
+export function getSilentGuidanceSteps(mode) {
+    switch (mode) {
+        case "investigation": return INVESTIGATION_STEPS;
+        case "operation": return OPERATION_STEPS;
+        case "content_iteration": return CONTENT_ITERATION_STEPS;
+        case "code_patch": return CODE_PATCH_STEPS;
+        case "unknown": return UNKNOWN_STEPS;
+    }
+}
+//# sourceMappingURL=templates.js.map

package/dist/src/understand/silent-guidance/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../../../src/understand/silent-guidance/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,kFAAkF;AAElF,MAAM,mBAAmB,GAAkC;IACzD;QACE,IAAI,EAAG,YAAY;QACnB,KAAK,EAAE,0FAA0F;KAClG;IACD;QACE,IAAI,EAAG,kBAAkB;QACzB,KAAK,EAAE,mFAAmF;KAC3F;IACD;QACE,IAAI,EAAG,mBAAmB;QAC1B,KAAK,EAAE,2FAA2F;KACnG;CACF,CAAC;AAEF,MAAM,eAAe,GAAkC;IACrD;QACE,IAAI,EAAG,YAAY;QACnB,KAAK,EAAE,2EAA2E;KACnF;IACD;QACE,IAAI,EAAG,kBAAkB;QACzB,KAAK,EAAE,iGAAiG;KACzG;IACD;QACE,IAAI,EAAG,mBAAmB;QAC1B,KAAK,EAAE,8FAA8F;KACtG;CACF,CAAC;AAEF,MAAM,uBAAuB,GAAkC;IAC7D;QACE,IAAI,EAAG,YAAY;QACnB,KAAK,EAAE,6EAA6E;KACrF;IACD;QACE,IAAI,EAAG,kBAAkB;QACzB,KAAK,EAAE,iGAAiG;KACzG;IACD;QACE,IAAI,EAAG,mBAAmB;QAC1B,KAAK,EAAE,8DAA8D;KACtE;CACF,CAAC;AAEF,MAAM,gBAAgB,GAAkC;IACtD;QACE,IAAI,EAAG,YAAY;QACnB,KAAK,EAAE,6CAA6C;KACrD;IACD;QACE,IAAI,EAAG,kBAAkB;QACzB,KAAK,EAAE,4DAA4D;KACpE;IACD;QACE,IAAI,EAAG,mBAAmB;QAC1B,KAAK,EAAE,wDAAwD;KAChE;CACF,CAAC;AAEF,MAAM,aAAa,GAAkC;IACnD;QACE,IAAI,EAAG,YAAY;QACnB,KAAK,EAAE,+EAA+E;KACvF;IACD;QACE,IAAI,EAAG,kBAAkB;QACzB,KAAK,EAAE,+GAA+G;KACvH;IACD;QACE,IAAI,EAAG,mBAAmB;QAC1B,KAAK,EAAE,mEAAmE;KAC3E;CACF,CAAC;AAEF,mFAAmF;AAEnF;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAwB;IAExB,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,eAAe,CAAC,CAAK,OAAO,mBAAmB,CAAC;QACrD,KAAK,WAAW,CAAC,CAAS,OAAO,eAAe,CAAC;QACjD,KAAK,mBAAmB,CAAC,CAAC,OAAO,uBAAuB,CAAC;QACzD,KAAK,YAAY,CAAC,CAAQ,OAAO,gBAAgB,CAAC;QAClD,KAAK,SAAS,CAAC,CAAW,OAAO,aAAa,CAAC;IACjD,CAAC;AACH,CAAC"}

package/dist/src/understand/silent-guidance/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Silent Guidance Mode — the shape-based template selector for bridge-silent flows.
+ *
+ * ── Purpose ─────────────────────────────────────────────────────────────────
+ *
+ * When the Intent Interpretation Bridge is eligible but no interpreter claims
+ * the input (bridgeSilenceReason === "no_interpreter_claimed"), the system
+ * still needs to show guidance.  The default code-patch template is often
+ * misleading for non-patch requests (ops, QA, content, schema, etc.).
+ *
+ * SilentGuidanceMode selects which generic template to render.
+ *
+ * ── What this is NOT ─────────────────────────────────────────────────────────
+ *
+ *   NOT an intent classifier        — produces no category or confidence
+ *   NOT an interpreter              — does not enter IntentInterpretation
+ *   NOT in UCP                      — no envelope emitted
+ *   NOT in GuidancePayload.interpretation — interpretation field unchanged
+ *   NOT authority-bearing           — does not affect mode, signal, intentState
+ *
+ * ── What this IS ─────────────────────────────────────────────────────────────
+ *
+ *   Purely presentation-level guidance shaping.
+ *   Replaces nextSteps in GuidancePayload with mode-appropriate generic steps.
+ *   missing[] is always preserved unchanged.
+ *
+ * ── Mode semantics ────────────────────────────────────────────────────────────
+ *
+ *   "investigation"     QA, debugging, bug reproduction, smoke tests, mocks
+ *   "operation"         Infra, deployments, pipelines, schema changes, migrations
+ *   "content_iteration" Copy, UX text, product description, taglines, user flow
+ *   "code_patch"        Explicit code patch intent not claimed by any interpreter
+ *   "unknown"           Fallback: vague, cross-domain, or ambiguous request shape
+ */
+export type SilentGuidanceMode = "investigation" | "operation" | "content_iteration" | "code_patch" | "unknown";
+//# sourceMappingURL=types.d.ts.map

package/dist/src/understand/silent-guidance/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/understand/silent-guidance/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,WAAW,GACX,mBAAmB,GACnB,YAAY,GACZ,SAAS,CAAC"}

package/dist/src/understand/silent-guidance/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/understand/silent-guidance/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/understand/silent-guidance/types.ts"],"names":[],"mappings":""}

package/dist/src/workflow/coordinator.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Phase 9C: Workflow coordinator.
+ *
+ * ── Purpose ───────────────────────────────────────────────────────────────────
+ *
+ *   Sequences CursorProductSession and ClaudeProductSession instances,
+ *   one at a time, through a human-authored list of task specs.
+ *
+ * ── What this is NOT (W1) ─────────────────────────────────────────────────────
+ *
+ *   NOT authority — calls session functions; makes no decisions.
+ *   NOT a planner — task specs are fixed at definition time; none are derived.
+ *   NOT a retry engine — retry creates a new session; H re-approves every time.
+ *   NOT a batch approver — each session requires explicit H approval (W2).
+ *   NOT stateful — all functions return new WorkflowRun objects.
+ *
+ * ── Function contract ─────────────────────────────────────────────────────────
+ *
+ *   createWorkflowRun(spec)               → "reviewing"
+ *   startWorkflow(run, ...)              → "task_ready" | "task_conflict" | "completed"
+ *   cancelWorkflow(run)                  → "stopped" (no session created)
+ *   advanceWorkflow(run, ...)             → "task_ready" | "task_conflict" | "completed"
+ *   acceptWorkflowConflict(run)           → "task_ready"
+ *   confirmWorkflowTask(run, yes)         → "task_approved" | "task_failed"
+ *   deliverWorkflowTask(run, ...)         → "running" | "task_scope" | "task_failed"
+ *   answerWorkflowScope(run, idx, ...)    → "task_approved" (→ call deliverWorkflowTask)
+ *   applyFailureAction(run, action, ...)  → "running" | "stopped"
+ *
+ * ── Shell loop ─────────────────────────────────────────────────────────────────
+ *
+ *   run = createWorkflowRun(spec)            // → "reviewing"
+ *   // (H confirms pre-flight list)
+ *   run = startWorkflow(run, ...)           // → "task_ready" | "task_conflict"
+ *   while (!isWorkflowTerminal(run)):
+ *     if "task_conflict": run = acceptWorkflowConflict(run)  // or reject
+ *     if "task_ready":    run = confirmWorkflowTask(run, yes)
+ *     if "task_approved": run = await deliverWorkflowTask(run, ...)
+ *     if "task_scope":    run = await answerWorkflowScope(run, idx, ...)
+ *                         run = await deliverWorkflowTask(run, ...)
+ *     if "task_failed":   run = applyFailureAction(run, action)
+ *     if "running":       run = advanceWorkflow(run, ...)
+ *
+ * ── Authority invariants (W1–W8) ──────────────────────────────────────────────
+ *
+ *   W2: confirmWorkflowTask(yes) → calls approve() only. deliverWorkflowTask
+ *       is a separate explicit call. The coordinator never auto-delivers.
+ *   W3: applyFailureAction("retry") creates a new session; never resumes.
+ *   W6: applyOCDOverride() adds to prohibited globs; never removes.
+ *   W7: task spec inputs are read-only; never modified after createWorkflowRun.
+ *   W8: runtime is taken from task spec; never derived or converted.
+ *
+ * See: docs/phase-9b-workflow-design.md
+ */
+import type { CursorOCDPolicy } from "../cursor/types.js";
+import type { ClaudeOCDPolicy } from "../claude/artifact-mapper.js";
+import type { ClaudeToolPolicy } from "../claude/types.js";
+import type { ClaudeGateDeps } from "../claude/delivery-gate.js";
+import type { WorkflowSpec, WorkflowRun, WorkflowPlugins } from "./types.js";
+import type { WorkflowRunPayload } from "../ucp/types.js";
+/**
+ * Create a new WorkflowRun from a spec.
+ *
+ * The run begins in "reviewing" phase (Phase 11D / WF-R1).
+ * No session is created until H explicitly starts the workflow via startWorkflow().
+ *
+ * WF-R2: currentSession is absent in "reviewing".
+ *
+ * @param opts.mode             "break_glass" to skip per-step human confirm (BG-1).
+ * @param opts.breakGlassReason Required when mode is "break_glass" (BG-4).
+ *                              Recorded in audit permanently (BG-3).
+ */
+export declare function createWorkflowRun(spec: WorkflowSpec, opts?: {
+    mode?: "normal" | "break_glass";
+    breakGlassReason?: string;
+}): WorkflowRun;
+/**
+ * Confirm the pre-flight review and start executing the first task.
+ *
+ * WF-R3: the only path out of "reviewing" into execution.
+ *
+ * Transitions "reviewing" → "idle" → immediately calls advanceWorkflow to
+ * prepare the first task. Returns the same result advanceWorkflow would:
+ * "task_ready" | "task_conflict" | "completed" (if all tasks auto-skip).
+ *
+ * Valid from "reviewing" only; no-op from any other phase.
+ */
+export declare function startWorkflow(run: WorkflowRun, cursorPolicy: CursorOCDPolicy, claudeOCDPolicy: ClaudeOCDPolicy, claudeToolPolicy: ClaudeToolPolicy): WorkflowRun;
+/**
+ * Cancel the workflow at the pre-flight stage.
+ *
+ * H declined to start. No session was ever created (WF-R1).
+ * Transitions "reviewing" → "stopped" cleanly.
+ *
+ * Valid from "reviewing" only; no-op from any other phase.
+ */
+export declare function cancelWorkflow(run: WorkflowRun): WorkflowRun;
+export declare function isWorkflowTerminal(run: WorkflowRun): boolean;
+/**
+ * Advance the workflow to the next task.
+ *
+ * Called when phase is "idle" or "running".
+ *
+ * Creates a new session for the current task spec, submits the task input,
+ * and transitions to "task_ready", "task_conflict", or "completed".
+ *
+ * Auto-skips tasks where intake returns a non-execute mode ("skipped_by_intake").
+ * This is the V1 default policy for non-execute inputs (see Phase 9B design).
+ *
+ * @param cursorPolicy    Workspace Cursor OCD policy (workflow override is applied internally).
+ * @param claudeOCDPolicy Workspace Claude OCD policy (workflow override is applied internally).
+ * @param claudeToolPolicy Claude tool policy.
+ */
+export declare function advanceWorkflow(run: WorkflowRun, cursorPolicy: CursorOCDPolicy, claudeOCDPolicy: ClaudeOCDPolicy, claudeToolPolicy: ClaudeToolPolicy): WorkflowRun;
+/**
+ * Accept the OCD conflict on the current task.
+ *
+ * Valid from "task_conflict" only.
+ * Transitions to "task_ready".
+ */
+export declare function acceptWorkflowConflict(run: WorkflowRun): WorkflowRun;
+/**
+ * Confirm (approve) or reject the current prepared task.
+ *
+ * Valid from "task_ready" and "task_conflict" (rejection path).
+ *
+ * yes=true  → calls approve() / approveClaude() → "task_approved"
+ * yes=false → calls reject() / rejectClaude()   → "task_failed" (outcome: "rejected")
+ *
+ * ── Proof W2 (never approves on behalf of H) ────────────────────────────────
+ *
+ *   This function calls approve() exactly once when yes=true.
+ *   It does NOT call deliver() or deliverClaude().
+ *   The session transitions to "approved", not "accepted".
+ *   deliverWorkflowTask() is the separate, explicit delivery step.
+ */
+export declare function confirmWorkflowTask(run: WorkflowRun, yes: boolean): WorkflowRun;
+/**
+ * Deliver the current approved task to its runtime.
+ *
+ * Valid from "task_approved" only.
+ *
+ * Outcome:
+ *   accepted    → record outcome, increment currentIndex → "running"
+ *   scope_question → "task_scope"
+ *   exec_error / blocked → "task_failed"
+ *
+ * @param plugins  WorkflowPlugins — coordinator picks the right one by runtime (W8 / Proof 3).
+ * @param storeDir UCP store directory.
+ * @param deps     Optional gate dependencies (for test injection, Claude only).
+ */
+export declare function deliverWorkflowTask(run: WorkflowRun, plugins: WorkflowPlugins, storeDir: string, deps?: ClaudeGateDeps): Promise<WorkflowRun>;
+/**
+ * Answer a scope clarification question for the current task.
+ *
+ * Valid from "task_scope" only.
+ * Transitions to "task_approved" so the caller can call deliverWorkflowTask again.
+ *
+ * @param choiceIdx 1-based index into the scope candidates.
+ *                  Out-of-range → returns state unchanged.
+ */
+export declare function answerWorkflowScope(run: WorkflowRun, choiceIdx: number): WorkflowRun;
+/**
+ * Apply a failure action to the current failed task.
+ *
+ * Valid from "task_failed" only.
+ *
+ * Actions:
+ *   stop  → "stopped" (terminal)
+ *   skip  → record as "skipped", advance currentIndex → "running"
+ *   retry → if retryCount < maxRetries: increment retryCount, reset session → "running"
+ *            if retryCount >= maxRetries: returns state unchanged (stop/skip only)
+ *
+ * W3: retry creates a new session via advanceWorkflow; no session is re-opened.
+ *
+ * @returns Next WorkflowRun. Caller must call advanceWorkflow() after "running".
+ */
+export declare function applyFailureAction(run: WorkflowRun, action: "stop" | "skip" | "retry"): WorkflowRun;
+/**
+ * buildWorkflowRunPayload — produce the UCP payload for ucp.workflow_run.v1.
+ *
+ * Called when the workflow reaches "completed" or "stopped" (W5).
+ * Not called for in-progress runs.
+ *
+ * @throws {Error} If run is not in a terminal phase.
+ */
+export declare function buildWorkflowRunPayload(run: WorkflowRun): WorkflowRunPayload;
+/**
+ * persistWorkflowRun — build a ucp.workflow_run.v1 envelope and persist it.
+ *
+ * This is fire-and-forget (uses persistEnvelope, not persistEnvelopeOrThrow).
+ * A persistence failure must NOT block the shell from rendering a terminal
+ * state to the user. The UCP record is an audit artifact, not a gate.
+ *
+ * @throws {Error} If run is not terminal. Call only after isWorkflowTerminal(run).
+ */
+export declare function persistWorkflowRun(run: WorkflowRun, storeDir: string): void;
+//# sourceMappingURL=coordinator.d.ts.map

package/dist/src/workflow/coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../../src/workflow/coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AA8BH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAO,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAO,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAQ,4BAA4B,CAAC;AAEnE,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EAOX,eAAe,EAGhB,MAAM,YAAY,CAAC;AAKpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAoK1D;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,YAAY,EAClB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE,WAAW,CA0Bb;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAe,WAAW,EAC7B,YAAY,EAAM,eAAe,EACjC,eAAe,EAAG,eAAe,EACjC,gBAAgB,EAAE,gBAAgB,GACjC,WAAW,CAMb;AAID;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAI5D;AAID,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAE5D;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAe,WAAW,EAC7B,YAAY,EAAM,eAAe,EACjC,eAAe,EAAG,eAAe,EACjC,gBAAgB,EAAE,gBAAgB,GACjC,WAAW,CA4Gb;AAID;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAkBpE;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,GAAG,WAAW,CAmD/E;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAO,WAAW,EACrB,OAAO,EAAG,eAAe,EACzB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAK,cAAc,GACvB,OAAO,CAAC,WAAW,CAAC,CA6HtB;AAID;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAsBpF;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAK,WAAW,EACnB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAChC,WAAW,CAuDb;AAID;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,WAAW,GAAG,kBAAkB,CAmC5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAI3E"}