@specforge/canary-cli 0.1.11 → 0.1.13

package/node_modules/@specforge/session-types/dist/runtime/lifecycle-contract.d.ts

@@ -0,0 +1,301 @@
+import type { PlanningPhase, PlanningSessionStatus, WorkPhase, WorkSessionStatus } from './enums.js';
+import type { PlanningOperationName } from './planning-operations.js';
+import type { WritePlan } from './write-plan.js';
+export type LifecycleEvent = 'start_planning_session' | 'action_planning_session' | 'complete_planning_session';
+/**
+ * The response shape returned by every planning lifecycle verb (SPS / APS / CPS),
+ * on BOTH success and denial branches.
+ *
+ * `sessionId`, `planningPhase`, and `planningStatus` are read from the session AFTER
+ * any state mutation the verb applied, so a single verb call returns enough state to
+ * drive the next agent-loop iteration without a follow-up read.
+ *
+ * Work + review lifecycles (M16–M25) specialise via `LifecycleResult<WorkAgentResponse>`
+ * / `LifecycleResult<ReviewAgentResponse>` rather than widening this shape.
+ */
+/**
+ * MB.10.5 — the exact repo-relative paths the CPS pass-1 asks the MCP-local to
+ * probe for existence. Rides on {@link PlanningAgentResponse.grepRequest}; the
+ * grep is scoped to EXACTLY these paths (no repo-wide scan).
+ */
+export interface GrepRequest {
+    paths: string[];
+}
+export interface PlanningAgentResponse {
+    sessionId: string;
+    planningPhase: PlanningPhase;
+    planningStatus: PlanningSessionStatus;
+    /**
+     * `'success'`/`'denied'` are the terminal verb outcomes. MB.10.5 adds
+     * `'evidence_required'` — a NON-COMMITTING, CLI-internal CPS pass-1 outcome:
+     * the verb needs real-repo file evidence (see {@link grepRequest}) that only
+     * the MCP-local can observe (the Lambda has no worktree). The CLI probes those
+     * paths and re-calls CPS with `existingFiles` injected (pass-2); the agent only
+     * ever sees the pass-2 `'success'`/`'denied'`. It never reaches a non-cli caller
+     * — the mcp-handler boundary injects `existingFiles: []` for non-cli origins so
+     * those callers get the strict verdict via the same presence-discriminator.
+     */
+    outcome: 'success' | 'denied' | 'evidence_required';
+    /**
+     * ME.15.3 — the LOCAL score of the single entity this verb touched
+     * (`update_ticket`/`update_epic` → that ticket/epic's per-entity score;
+     * `update_spec` → the spec's local score), versus its per-phase threshold →
+     * that entity's own pass/fail. `null` for verbs that don't touch a single
+     * scored entity (SPS/CPS, `get_planning_status`, denials) and for the binary
+     * structural phases (epic/ticket_decomposition, cross_validation) which have
+     * no per-entity score. Do NOT confuse with the phase average (`avgLocalScore`).
+     */
+    localScore: number | null;
+    /**
+     * ME.15.3 — the phase AVERAGE local score across the entities the validator
+     * scored this phase (the number that used to be mislabeled `scoreLocal`).
+     * `null` for the binary phases (no per-entity score) and denials.
+     */
+    avgLocalScore: number | null;
+    /**
+     * ME.15.3 (ex-`scoreGlobal`) — the real WEIGHTED global readiness score
+     * (ME.13.3 Bug #2 carrier). Never a copy of the local score.
+     */
+    globalScore: number | null;
+    gatePassed: boolean | null;
+    guidance: string;
+    /**
+     * MB.10.5 — present ONLY on `outcome: 'evidence_required'`. The union of the
+     * consumed-but-uncreated paths (consume-exists) and ALL `filesToBeCreated`
+     * paths (create-fresh) the file-provenance model needs real-repo evidence for.
+     * The MCP-local probes exactly these paths and re-submits the existing subset
+     * as `existingFiles` (pass-2).
+     */
+    grepRequest?: GrepRequest;
+}
+/**
+ * A machine-readable pointer to the next action the work agent should take, surfaced on
+ * `WorkAgentResponse` so a single verb call drives the next agent-loop iteration without a
+ * follow-up read. The human-readable next-step instruction is composed into `guidance`
+ * (prose/content — M18); these are the bare refs. The assay (M17) produces the rich
+ * `NextStep` (in `@specforge/assayforge`); the work lifecycle (M16) projects it down to this
+ * wire-safe ref (session-types cannot import assayforge — the dependency runs the other way).
+ */
+export interface WorkNextStepRef {
+    /** The work dimension the next action targets. */
+    workPhase: WorkPhase;
+    /**
+     * The plan entity the next action concerns when anchored to one — a step id,
+     * acceptance-criterion id, or file path. Omitted for aggregate / terminal steps.
+     */
+    entityId?: string;
+}
+/**
+ * The response shape returned by every work lifecycle verb (SWS / AWS / CWS), on BOTH
+ * success and denial branches — the work sibling of `PlanningAgentResponse`, specialised
+ * via `LifecycleResult<WorkAgentResponse>` (M6.5 generic; M16 implements the verbs).
+ *
+ * `sessionId`, `workPhase`, and `workStatus` are non-optional on EVERY branch (success AND
+ * denied), read from the session AFTER any state mutation the verb applied, so a single verb
+ * call returns enough state to drive the next agent-loop iteration without a follow-up read.
+ *
+ * `guidance` is composed verbatim via the agent-directed prose pipeline (never parsed
+ * downstream). The work-specific fields (`progress`, `coherence`, `gatePassed`,
+ * `nextStepRefs`) carry the assay's per-call signals; their content/prose lands in M18 — the
+ * TYPE lands here (M14.1).
+ */
+export interface WorkAgentResponse {
+    /** The work session id (echoed on every branch, incl. denials). */
+    sessionId: string;
+    /** Current progress stage AFTER the verb's mutation. */
+    workPhase: WorkPhase;
+    /** Post-mutation work-session lifecycle state. */
+    workStatus: WorkSessionStatus;
+    /** Self-discriminates success vs. negotiated denial (both ride the lifecycle envelope). */
+    outcome: 'success' | 'denied';
+    /** Aggregate ticket completion progress; `null` when no assay has run for the verb. */
+    progress: number | null;
+    /** Coherence score from the assay (files/tests justification); `null` when not applicable. */
+    coherence: number | null;
+    /** Gate verdict; `null` when no gate has run for the phase. */
+    gatePassed: boolean | null;
+    /** Refs to the next action(s) the agent should take; `null` on terminal / denial branches. */
+    nextStepRefs: WorkNextStepRef[] | null;
+    /** Composed agent-facing prose — read verbatim, never parsed. */
+    guidance: string;
+}
+/**
+ * Two generic axes (see M6.5 §A0.2):
+ *  - `R` (response): defaults to `PlanningAgentResponse`; work/review lifecycles override.
+ *  - `W` (writePlan): defaults to `unknown` so generic call sites stay agnostic.
+ *    `@specforge/lifecycle` binds `W = WritePlan` (now defined here in session-types —
+ *    M7.4d) via its own `LifecycleResult` subtype.
+ */
+export interface LifecycleResult<R = PlanningAgentResponse, W = unknown> {
+    response: R;
+    writePlan?: W;
+}
+/**
+ * Per-verb payloads for the planning lifecycle dispatch union. These are the
+ * wire contracts the resolver/CLI map AppSync/REST arguments into; the lifecycle
+ * verbs consume them directly. Relocated from `@specforge/lifecycle` in M7.4d so
+ * `@specforge/resolvers` can type the planning-resolver handler without importing
+ * the lifecycle package (monorepo-topology §2.1d).
+ */
+export interface StartPlanningPayload {
+    /**
+     * Injected by the client (CLI mcp-local / webapp), NOT derived server-side.
+     * The public `start_planning_session` tool already declares `projectId` required;
+     * SPS now consumes the injected value instead of reading it off the spec row, so
+     * the project scope is client-authoritative.
+     */
+    projectId: string;
+    specId: string;
+    userId?: string;
+}
+/**
+ * MB.11.1 — payload for the `justify` operation carried on
+ * {@link ActionPlanningPayload.payload} when `operation === 'justify'`. Declares a
+ * field N/A. The tool-level `type: 'justify'` discriminant is mapped into
+ * `ActionPlanningPayload.operation`, so the payload the verb consumes is the
+ * type-stripped rest (`{ scope, entityId, reason }`) — the same convention every
+ * other planning op follows (e.g. `update_ticket` → `{ id, fields }`, no `type`).
+ *
+ *  - `scope`    — the CANONICAL `fieldDeclarations` key the checks read (the exact
+ *                 bare key, e.g. `dependencies`, `codeReferences`, `apiContracts`).
+ *  - `entityId` — the spec/epic/ticket the field belongs to (resolved server-side;
+ *                 ids are unique across the spec).
+ *  - `reason`   — the justification (≥ `config.naReason.minLength` = 20 chars).
+ */
+export interface JustifyPayload {
+    scope: string;
+    entityId: string;
+    reason: string;
+}
+/**
+ * MB.11.1 — payload for the `unjustify` operation (the paired remove op). Clears the
+ * `fieldDeclarations[scope]` declaration. No `reason` (a delete is unconditional; a
+ * no-op if the key is absent).
+ */
+export interface UnjustifyPayload {
+    scope: string;
+    entityId: string;
+}
+export interface ActionPlanningPayload {
+    sessionId: string;
+    operation: PlanningOperationName;
+    payload: unknown;
+    userId?: string;
+    /**
+     * M11.1 — actor discriminator. Derived SERVER-SIDE from the authenticated
+     * identity (webapp custom mutation → `'human'`; MCP/CLI → `'agent'`), never
+     * trusted from the client payload. Defaults to `'agent'` when omitted.
+     *
+     * It drives BOTH the audit row's `performedByActor` AND the actor-conditional
+     * post-APS status of an edit on an `awaiting_human_review` session:
+     *  - `'human'` → the session STAYS `awaiting_human_review` (re-scores in place;
+     *    the human never leaves the review window by editing).
+     *  - `'agent'` (default) → the session flips to `active` exactly as before (the
+     *    agent then re-requests the gate via a subsequent CPS).
+     */
+    actor?: 'agent' | 'human';
+}
+export interface CompletePlanningPayload {
+    sessionId: string;
+    userId?: string;
+    /**
+     * MB.10.5 grep evidence, injected by the MCP-local CLI double-call: the subset
+     * of the pass-1 `grepRequest.paths` that actually exist in the real repository.
+     * PRESENCE (even `[]`) is the "probed" marker → the verb runs the real gate
+     * with `E = existingFiles ∪ createdPaths` (pass-2). ABSENT → pass-1: the verb
+     * returns `evidence_required` carrying `grepRequest` and commits NOTHING. The
+     * mcp-handler boundary injects `[]` for any non-cli origin so only the cli
+     * double-call ever sends it absent (only the cli knows how to probe + re-call).
+     */
+    existingFiles?: string[];
+}
+/**
+ * Payload-carrying dispatch union accepted by `Lifecycle.handle`. Discriminated
+ * by `type`. (Distinct from the string-only `LifecycleEvent` above, which just
+ * enumerates the verb names.)
+ */
+export type PlanningLifecycleEvent = {
+    type: 'start_planning_session';
+    payload: StartPlanningPayload;
+} | {
+    type: 'action_planning_session';
+    payload: ActionPlanningPayload;
+} | {
+    type: 'complete_planning_session';
+    payload: CompletePlanningPayload;
+};
+/**
+ * The planning lifecycle dispatch contract. The implementation factory
+ * (`createLifecycle`) stays in `@specforge/lifecycle`; only this interface lives
+ * here so downstream Lambda factories can type against it without a lifecycle
+ * import (M7.4d).
+ */
+export interface Lifecycle {
+    handle(event: PlanningLifecycleEvent): Promise<LifecycleResult<PlanningAgentResponse, WritePlan>>;
+}
+/**
+ * The string-only enumeration of the work lifecycle verbs (the work sibling of
+ * the planning `LifecycleEvent`). All three are agent-facing and keyed by
+ * `ticketId`; the human surfaces (resolution window M21, abort kill-switch M24)
+ * are separate webapp verbs and are NOT part of this agent dispatch union.
+ */
+export type WorkLifecycleVerb = 'start_work_session' | 'action_work_session' | 'complete_work_session';
+/**
+ * SWS — `start_work_session`. Starts (or attaches to) the WorkSession for a
+ * ticket, creating the parent ImplementationSession on first start for the spec.
+ * Keyed by `ticketId` (the session id is assigned by the verb). `worktreePath` /
+ * `branch` are the optional worktree provenance the MCP-local reports (M23.2) and
+ * SWS persists (M16.2) when the agent runs inside a git worktree.
+ */
+export interface StartWorkSessionPayload {
+    ticketId: string;
+    userId?: string;
+    worktreePath?: string;
+    branch?: string;
+    /**
+     * Clean-git-workspace status injected by the MCP-local (M23). `false` = the
+     * agent's worktree has uncommitted changes → SWS denies (`git_dirty`,
+     * "clean your git workspace before starting"). `true` / absent = clean (no
+     * denial), so non-git callers still start. M16 consumes this as a MOCK input;
+     * M23 wires the real `git status` injection.
+     */
+    gitClean?: boolean;
+}
+/**
+ * AWS — `action_work_session`. Updates the WorkSession checklist state (step /
+ * AC / test / file progress, discovery, blocker) for the ticket's active session.
+ * The structured action payload — including the action-operation discriminator —
+ * is typed at dispatch time in M16; held as `unknown` here so generic call sites
+ * stay agnostic (mirrors the planning `ActionPlanningPayload.payload`).
+ */
+export interface ActionWorkSessionPayload {
+    ticketId: string;
+    payload: unknown;
+    userId?: string;
+}
+/**
+ * CWS — `complete_work_session`. Finalizes the ticket's active WorkSession (and,
+ * when it is the last open WorkSession of the spec, the parent
+ * ImplementationSession + spec→done). Keyed by `ticketId`.
+ */
+export interface CompleteWorkSessionPayload {
+    ticketId: string;
+    userId?: string;
+}
+/**
+ * Payload-carrying dispatch union accepted by the work lifecycle (the work
+ * counterpart of `PlanningLifecycleEvent`). Discriminated by `type`. (Distinct
+ * from the string-only `WorkLifecycleVerb` above, which just enumerates the verb
+ * names.) The work `Lifecycle.handle` overload that consumes this lands in M16.
+ */
+export type WorkLifecycleEvent = {
+    type: 'start_work_session';
+    payload: StartWorkSessionPayload;
+} | {
+    type: 'action_work_session';
+    payload: ActionWorkSessionPayload;
+} | {
+    type: 'complete_work_session';
+    payload: CompleteWorkSessionPayload;
+};
+//# sourceMappingURL=lifecycle-contract.d.ts.map

package/node_modules/@specforge/session-types/dist/runtime/lifecycle-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-contract.d.ts","sourceRoot":"","sources":["../../src/runtime/lifecycle-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,qBAAqB,EACrB,SAAS,EACT,iBAAiB,EAClB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,MAAM,cAAc,GACtB,wBAAwB,GACxB,yBAAyB,GACzB,2BAA2B,CAAC;AAEhC;;;;;;;;;;GAUG;AACH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,aAAa,CAAC;IAC7B,cAAc,EAAE,qBAAqB,CAAC;IACtC;;;;;;;;;OASG;IACH,OAAO,EAAE,SAAS,GAAG,QAAQ,GAAG,mBAAmB,CAAC;IACpD;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,SAAS,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,EAAE,SAAS,CAAC;IACrB,kDAAkD;IAClD,UAAU,EAAE,iBAAiB,CAAC;IAC9B,2FAA2F;IAC3F,OAAO,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC9B,uFAAuF;IACvF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,8FAA8F;IAC9F,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+DAA+D;IAC/D,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3B,8FAA8F;IAC9F,YAAY,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC;IACvC,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,qBAAqB,EAAE,CAAC,GAAG,OAAO;IACrE,QAAQ,EAAE,CAAC,CAAC;IACZ,SAAS,CAAC,EAAE,CAAC,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,qBAAqB,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,yBAAyB,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,2BAA2B,CAAC;IAAC,OAAO,EAAE,uBAAuB,CAAA;CAAE,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IAGxB,MAAM,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAC,CAAC;CACnG;AAYD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,oBAAoB,GACpB,qBAAqB,GACrB,uBAAuB,CAAC;AAE5B;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,uBAAuB,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,OAAO,EAAE,wBAAwB,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,OAAO,EAAE,0BAA0B,CAAA;CAAE,CAAC"}

package/node_modules/@specforge/session-types/dist/runtime/lifecycle-contract.js

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

package/node_modules/@specforge/session-types/dist/runtime/lifecycle-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-contract.js","sourceRoot":"","sources":["../../src/runtime/lifecycle-contract.ts"],"names":[],"mappings":""}

package/node_modules/@specforge/session-types/dist/runtime/lifecycle-planning-guidance.d.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+export declare const LifecyclePlanningGuidanceSchema: z.ZodObject<{
+    variant: z.ZodEnum<["denied", "gate_failed", "gate_passed", "human_handover", "human_feedback", "phase_advance", "phase_rollback", "phase_complete", "phase_status_report", "awaiting_human_review_handover", "human_feedback_received", "human_rejected_no_feedback", "phase_advanced_after_approve", "session_closed"]>;
+    fieldsToFill: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        fieldId: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        required: z.ZodBoolean;
+        currentState: z.ZodEnum<["empty", "partial", "filled", "na"]>;
+        minCount: z.ZodOptional<z.ZodNumber>;
+        examples: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        shape: z.ZodOptional<z.ZodString>;
+        interview_hooks: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        naEligible: z.ZodOptional<z.ZodBoolean>;
+        na_when: z.ZodOptional<z.ZodString>;
+        tier: z.ZodOptional<z.ZodEnum<["critical", "recommended", "standard"]>>;
+    }, "strip", z.ZodTypeAny, {
+        fieldId: string;
+        name: string;
+        description: string;
+        required: boolean;
+        currentState: "empty" | "partial" | "filled" | "na";
+        minCount?: number | undefined;
+        examples?: string[] | undefined;
+        shape?: string | undefined;
+        interview_hooks?: string[] | undefined;
+        naEligible?: boolean | undefined;
+        na_when?: string | undefined;
+        tier?: "critical" | "recommended" | "standard" | undefined;
+    }, {
+        fieldId: string;
+        name: string;
+        description: string;
+        required: boolean;
+        currentState: "empty" | "partial" | "filled" | "na";
+        minCount?: number | undefined;
+        examples?: string[] | undefined;
+        shape?: string | undefined;
+        interview_hooks?: string[] | undefined;
+        naEligible?: boolean | undefined;
+        na_when?: string | undefined;
+        tier?: "critical" | "recommended" | "standard" | undefined;
+    }>, "many">>;
+    humanHandoff: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        observatoryLink: z.ZodOptional<z.ZodString>;
+        iterationNeeded: z.ZodOptional<z.ZodObject<{
+            focus: z.ZodString;
+            suggestion: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            focus: string;
+            suggestion: string;
+        }, {
+            focus: string;
+            suggestion: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        observatoryLink?: string | undefined;
+        iterationNeeded?: {
+            focus: string;
+            suggestion: string;
+        } | undefined;
+    }, {
+        message: string;
+        observatoryLink?: string | undefined;
+        iterationNeeded?: {
+            focus: string;
+            suggestion: string;
+        } | undefined;
+    }>>;
+    postApprovalActions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    composedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    variant: "denied" | "gate_failed" | "gate_passed" | "human_handover" | "human_feedback" | "phase_advance" | "phase_rollback" | "phase_complete" | "phase_status_report" | "awaiting_human_review_handover" | "human_feedback_received" | "human_rejected_no_feedback" | "phase_advanced_after_approve" | "session_closed";
+    composedAt: string;
+    fieldsToFill?: {
+        fieldId: string;
+        name: string;
+        description: string;
+        required: boolean;
+        currentState: "empty" | "partial" | "filled" | "na";
+        minCount?: number | undefined;
+        examples?: string[] | undefined;
+        shape?: string | undefined;
+        interview_hooks?: string[] | undefined;
+        naEligible?: boolean | undefined;
+        na_when?: string | undefined;
+        tier?: "critical" | "recommended" | "standard" | undefined;
+    }[] | undefined;
+    humanHandoff?: {
+        message: string;
+        observatoryLink?: string | undefined;
+        iterationNeeded?: {
+            focus: string;
+            suggestion: string;
+        } | undefined;
+    } | undefined;
+    postApprovalActions?: string[] | undefined;
+}, {
+    variant: "denied" | "gate_failed" | "gate_passed" | "human_handover" | "human_feedback" | "phase_advance" | "phase_rollback" | "phase_complete" | "phase_status_report" | "awaiting_human_review_handover" | "human_feedback_received" | "human_rejected_no_feedback" | "phase_advanced_after_approve" | "session_closed";
+    composedAt: string;
+    fieldsToFill?: {
+        fieldId: string;
+        name: string;
+        description: string;
+        required: boolean;
+        currentState: "empty" | "partial" | "filled" | "na";
+        minCount?: number | undefined;
+        examples?: string[] | undefined;
+        shape?: string | undefined;
+        interview_hooks?: string[] | undefined;
+        naEligible?: boolean | undefined;
+        na_when?: string | undefined;
+        tier?: "critical" | "recommended" | "standard" | undefined;
+    }[] | undefined;
+    humanHandoff?: {
+        message: string;
+        observatoryLink?: string | undefined;
+        iterationNeeded?: {
+            focus: string;
+            suggestion: string;
+        } | undefined;
+    } | undefined;
+    postApprovalActions?: string[] | undefined;
+}>;
+export type LifecyclePlanningGuidance = z.infer<typeof LifecyclePlanningGuidanceSchema>;
+//# sourceMappingURL=lifecycle-planning-guidance.d.ts.map

package/node_modules/@specforge/session-types/dist/runtime/lifecycle-planning-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-planning-guidance.d.ts","sourceRoot":"","sources":["../../src/runtime/lifecycle-planning-guidance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0B1C,CAAC;AAEH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC"}

package/node_modules/@specforge/session-types/dist/runtime/lifecycle-planning-guidance.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { GUIDANCE_VARIANTS, FIELD_STATES } from './enums.js';
+export const LifecyclePlanningGuidanceSchema = z.object({
+    variant: z.enum(GUIDANCE_VARIANTS),
+    fieldsToFill: z.array(z.object({
+        fieldId: z.string(),
+        name: z.string(),
+        description: z.string(),
+        required: z.boolean(),
+        currentState: z.enum(FIELD_STATES),
+        minCount: z.number().int().nonnegative().optional(),
+        examples: z.array(z.string()).optional(),
+        shape: z.string().optional(),
+        interview_hooks: z.array(z.string()).optional(),
+        naEligible: z.boolean().optional(),
+        na_when: z.string().optional(),
+        tier: z.enum(['critical', 'recommended', 'standard']).optional(),
+    })).optional(),
+    humanHandoff: z.object({
+        message: z.string(),
+        observatoryLink: z.string().optional(),
+        iterationNeeded: z.object({
+            focus: z.string(),
+            suggestion: z.string(),
+        }).optional(),
+    }).optional(),
+    postApprovalActions: z.array(z.string()).optional(),
+    composedAt: z.string().datetime(),
+});
+//# sourceMappingURL=lifecycle-planning-guidance.js.map

package/node_modules/@specforge/session-types/dist/runtime/lifecycle-planning-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-planning-guidance.js","sourceRoot":"","sources":["../../src/runtime/lifecycle-planning-guidance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7D,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC;IAClC,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;QAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;QACnB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;QACrB,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC;QAClC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;QACnD,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;QACxC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC5B,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;QAC/C,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;QAClC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC9B,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE;KACjE,CAAC,CAAC,CAAC,QAAQ,EAAE;IACd,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC;QACrB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;QACnB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QACtC,eAAe,EAAE,CAAC,CAAC,MAAM,CAAC;YACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;YACjB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;SACvB,CAAC,CAAC,QAAQ,EAAE;KACd,CAAC,CAAC,QAAQ,EAAE;IACb,mBAAmB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACnD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC"}

package/node_modules/@specforge/session-types/dist/runtime/parsed-git-evidence.d.ts

@@ -0,0 +1,4 @@
+import type { z } from 'zod';
+import type { ParsedGitEvidenceSchema } from '../schema/parsed-git-evidence.js';
+export type ParsedGitEvidence = z.infer<typeof ParsedGitEvidenceSchema>;
+//# sourceMappingURL=parsed-git-evidence.d.ts.map

package/node_modules/@specforge/session-types/dist/runtime/parsed-git-evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsed-git-evidence.d.ts","sourceRoot":"","sources":["../../src/runtime/parsed-git-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAEhF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/node_modules/@specforge/session-types/dist/runtime/parsed-git-evidence.js

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

package/node_modules/@specforge/session-types/dist/runtime/parsed-git-evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsed-git-evidence.js","sourceRoot":"","sources":["../../src/runtime/parsed-git-evidence.ts"],"names":[],"mappings":""}

package/node_modules/@specforge/session-types/dist/runtime/planning-config.d.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+/**
+ * Planning lifecycle config — the canonical contract type, resolved per-project/spec
+ * and persisted via the IConfigStore (domain `planning-lifecycle`). Lives here in
+ * session-types (alongside the other planning contracts + IConfigStore) so every
+ * consumer shares ONE source: the lifecycle resolver, and the M8.7 project-stream
+ * config-bootstrap in operations, both import from here — no operations→lifecycle dep.
+ *
+ * Behaviour (deepMerge + PlanningLifecycleConfigResolver) stays in @specforge/lifecycle.
+ */
+export declare const PLANNING_LIFECYCLE_CONFIG_DOMAIN: "planning-lifecycle";
+export declare const PLANNING_LIFECYCLE_CONFIG_SCHEMA_VERSION = 2;
+export declare const PlanningLifecycleConfigSchema: z.ZodObject<{
+    gateResultCacheTtlMs: z.ZodNumber;
+    observatoryBaseUrl: z.ZodString;
+    guidance: z.ZodObject<{
+        maxNextEntitiesToShow: z.ZodNumber;
+        fieldRenderDetail: z.ZodOptional<z.ZodEnum<["rich", "concise"]>>;
+    }, "strip", z.ZodTypeAny, {
+        maxNextEntitiesToShow: number;
+        fieldRenderDetail?: "rich" | "concise" | undefined;
+    }, {
+        maxNextEntitiesToShow: number;
+        fieldRenderDetail?: "rich" | "concise" | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    gateResultCacheTtlMs: number;
+    observatoryBaseUrl: string;
+    guidance: {
+        maxNextEntitiesToShow: number;
+        fieldRenderDetail?: "rich" | "concise" | undefined;
+    };
+}, {
+    gateResultCacheTtlMs: number;
+    observatoryBaseUrl: string;
+    guidance: {
+        maxNextEntitiesToShow: number;
+        fieldRenderDetail?: "rich" | "concise" | undefined;
+    };
+}>;
+export type PlanningLifecycleConfig = z.infer<typeof PlanningLifecycleConfigSchema>;
+/**
+ * PlanningLifecycleConfigOverridesSchema — a permissive DeepPartial of
+ * {@link PlanningLifecycleConfigSchema}. A project-level override is a sparse
+ * `DeepPartial<PlanningLifecycleConfig>` (e.g. `{ guidance: { maxNextEntitiesToShow: 5 } }`).
+ *
+ * `PlanningLifecycleConfigSchema` is a plain `ZodObject` tree of objects + primitives with
+ * NO cross-field refinements, so `.deepPartial()` is safe here (no `ZodEffects` to trip
+ * over, unlike the validator's `ValidatorConfigSchema`). The full schema is still re-checked
+ * on the deepMerged result by `validateOverrides` in @specforge/lifecycle.
+ */
+export declare const PlanningLifecycleConfigOverridesSchema: z.ZodObject<{
+    gateResultCacheTtlMs: z.ZodOptional<z.ZodNumber>;
+    observatoryBaseUrl: z.ZodOptional<z.ZodString>;
+    guidance: z.ZodOptional<z.ZodObject<{
+        maxNextEntitiesToShow: z.ZodOptional<z.ZodNumber>;
+        fieldRenderDetail: z.ZodOptional<z.ZodOptional<z.ZodEnum<["rich", "concise"]>>>;
+    }, "strip", z.ZodTypeAny, {
+        maxNextEntitiesToShow?: number | undefined;
+        fieldRenderDetail?: "rich" | "concise" | undefined;
+    }, {
+        maxNextEntitiesToShow?: number | undefined;
+        fieldRenderDetail?: "rich" | "concise" | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    gateResultCacheTtlMs?: number | undefined;
+    observatoryBaseUrl?: string | undefined;
+    guidance?: {
+        maxNextEntitiesToShow?: number | undefined;
+        fieldRenderDetail?: "rich" | "concise" | undefined;
+    } | undefined;
+}, {
+    gateResultCacheTtlMs?: number | undefined;
+    observatoryBaseUrl?: string | undefined;
+    guidance?: {
+        maxNextEntitiesToShow?: number | undefined;
+        fieldRenderDetail?: "rich" | "concise" | undefined;
+    } | undefined;
+}>;
+export type PlanningLifecycleConfigOverrides = z.infer<typeof PlanningLifecycleConfigOverridesSchema>;
+export declare const PLANNING_LIFECYCLE_DEFAULTS: PlanningLifecycleConfig;
+//# sourceMappingURL=planning-config.d.ts.map

package/node_modules/@specforge/session-types/dist/runtime/planning-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning-config.d.ts","sourceRoot":"","sources":["../../src/runtime/planning-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,EAAG,oBAA6B,CAAC;AAG9E,eAAO,MAAM,wCAAwC,IAAI,CAAC;AAE1D,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuBxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;;;;;;;;GASG;AACH,eAAO,MAAM,sCAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA8C,CAAC;AAClG,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sCAAsC,CAAC,CAAC;AAKtG,eAAO,MAAM,2BAA2B,EAAE,uBAOzC,CAAC"}

package/node_modules/@specforge/session-types/dist/runtime/planning-config.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+/**
+ * Planning lifecycle config — the canonical contract type, resolved per-project/spec
+ * and persisted via the IConfigStore (domain `planning-lifecycle`). Lives here in
+ * session-types (alongside the other planning contracts + IConfigStore) so every
+ * consumer shares ONE source: the lifecycle resolver, and the M8.7 project-stream
+ * config-bootstrap in operations, both import from here — no operations→lifecycle dep.
+ *
+ * Behaviour (deepMerge + PlanningLifecycleConfigResolver) stays in @specforge/lifecycle.
+ */
+export const PLANNING_LIFECYCLE_CONFIG_DOMAIN = 'planning-lifecycle';
+// ME.10.5 — bumped 1 → 2 after the clean-break trim (thresholds, arrayCountPhases
+// removed; gate knobs moved to the validator config). No migration — greenfield wipe.
+export const PLANNING_LIFECYCLE_CONFIG_SCHEMA_VERSION = 2;
+export const PlanningLifecycleConfigSchema = z.object({
+    // ME.10.3 — the entity-count bounds (minEpics/maxEpics/min/maxTicketsPerEpic) moved
+    // to the validator config (domain `planning`,
+    // ValidatorConfig.structuralRequirements.arrayMin/MaxCounts) as the single owner.
+    // ME.10.4 — the blueprint:epic ratio also moved to the validator config
+    // (ValidatorConfig.crossValidation.ratios.blueprintToEpic.min), emptying
+    // `arrayCountPhases` entirely — the object is gone.
+    gateResultCacheTtlMs: z.number().int(), // CPS stale-cache check (default: 5 minutes)
+    // ME.10.8 — `.url()`-validated so a non-URL override is a value error (not just a
+    // UI gate). The env-aware host is resolved SERVER-SIDE at handover-link-build time
+    // (process.env.OBSERVATORY_BASE_URL ?? config.observatoryBaseUrl); this static
+    // default stays free of process.env so it bundles identically into the webapp client.
+    observatoryBaseUrl: z.string().url(),
+    guidance: z.object({
+        // Max entities shown in the "next to fill" block during expansion-phase APS guidance
+        // (epic_expansion / ticket_expansion). Caps response size. Default: 3.
+        maxNextEntitiesToShow: z.number().int(),
+        // Fidelity of the phase-entry field block (composePhaseIntro). Optional; absent ⇒ 'rich'.
+        //  - 'rich'    → full per-field render (shape, interview hooks, examples, NA mechanism,
+        //                min count, tier) — the agent fills without guessing. Default.
+        //  - 'concise' → one line per field (name — description) + an optional list. Lighter.
+        fieldRenderDetail: z.enum(['rich', 'concise']).optional(),
+    }),
+});
+/**
+ * PlanningLifecycleConfigOverridesSchema — a permissive DeepPartial of
+ * {@link PlanningLifecycleConfigSchema}. A project-level override is a sparse
+ * `DeepPartial<PlanningLifecycleConfig>` (e.g. `{ guidance: { maxNextEntitiesToShow: 5 } }`).
+ *
+ * `PlanningLifecycleConfigSchema` is a plain `ZodObject` tree of objects + primitives with
+ * NO cross-field refinements, so `.deepPartial()` is safe here (no `ZodEffects` to trip
+ * over, unlike the validator's `ValidatorConfigSchema`). The full schema is still re-checked
+ * on the deepMerged result by `validateOverrides` in @specforge/lifecycle.
+ */
+export const PlanningLifecycleConfigOverridesSchema = PlanningLifecycleConfigSchema.deepPartial();
+// ---------------------------------------------------------------------------
+// PLANNING_LIFECYCLE_DEFAULTS — baseline merged under project/spec overrides.
+// ---------------------------------------------------------------------------
+export const PLANNING_LIFECYCLE_DEFAULTS = {
+    gateResultCacheTtlMs: 5 * 60 * 1000,
+    observatoryBaseUrl: 'https://specforge.tech',
+    guidance: {
+        maxNextEntitiesToShow: 3,
+        fieldRenderDetail: 'rich',
+    },
+};
+//# sourceMappingURL=planning-config.js.map

package/node_modules/@specforge/session-types/dist/runtime/planning-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning-config.js","sourceRoot":"","sources":["../../src/runtime/planning-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,oBAA6B,CAAC;AAC9E,kFAAkF;AAClF,sFAAsF;AACtF,MAAM,CAAC,MAAM,wCAAwC,GAAG,CAAC,CAAC;AAE1D,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IACpD,oFAAoF;IACpF,8CAA8C;IAC9C,kFAAkF;IAClF,wEAAwE;IACxE,yEAAyE;IACzE,oDAAoD;IACpD,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAI,6CAA6C;IACvF,kFAAkF;IAClF,mFAAmF;IACnF,+EAA+E;IAC/E,sFAAsF;IACtF,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACpC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;QACjB,qFAAqF;QACrF,uEAAuE;QACvE,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QACvC,0FAA0F;QAC1F,wFAAwF;QACxF,+EAA+E;QAC/E,sFAAsF;QACtF,iBAAiB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE;KAC1D,CAAC;CACH,CAAC,CAAC;AAGH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG,6BAA6B,CAAC,WAAW,EAAE,CAAC;AAGlG,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,2BAA2B,GAA4B;IAClE,oBAAoB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI;IACnC,kBAAkB,EAAE,wBAAwB;IAC5C,QAAQ,EAAE;QACR,qBAAqB,EAAE,CAAC;QACxB,iBAAiB,EAAE,MAAM;KAC1B;CACF,CAAC"}