@haaaiawd/second-nature 0.1.33 → 0.1.38

package/runtime/core/second-nature/heartbeat/heartbeat-loop.d.ts

@@ -23,6 +23,8 @@ import type { ConnectorExecutor } from "../../../connectors/base/contract.js";
 import type { CapabilityContractRegistry } from "../../../connectors/base/manifest.js";
 import type { NarrativeStateStore } from "../../../storage/narrative/narrative-state-store.js";
 import type { NarrativeTracePayload } from "../../../observability/services/lived-experience-audit.js";
+import type { ExperienceWriter } from "../body/tool-experience/experience-writer.js";
+import type { QuietDreamSchedulePort } from "../quiet/run-source-backed-quiet.js";
 export interface HeartbeatDecisionTracePayload {
     scope: RuntimeScope;
     status: HeartbeatCycleStatus;
@@ -43,12 +45,14 @@ export interface HeartbeatOutreachDispatchDeps {
 /** Optional Quiet orchestration: when set, quiet/reflection allows run source-backed Quiet writer (T2.3.3). */
 export interface HeartbeatQuietWorkflowDeps {
     workspaceRoot: string;
+    /** v7 T-V7C.C.3: when present, a successful Quiet write auto-triggers Dream scheduling. */
+    dreamSchedulePort?: QuietDreamSchedulePort;
 }
 /**
  * Resolves the heartbeat outcome for a guard-allowed intent (outreach dispatch, quiet orchestration, or default).
  * Exported for unit tests (CR-M1 wiring).
  */
-export declare function resolveAllowedIntentResult(intent: CandidateIntent, runtime: HeartbeatRuntimeSnapshot, inputs: SnapshotInputs, signal: HeartbeatSignal, deps: Pick<HeartbeatDeps, "outreachDispatch" | "quietWorkflow" | "connectorExecutor" | "state" | "workspaceRoot">): Promise<HeartbeatCycleResult>;
+export declare function resolveAllowedIntentResult(intent: CandidateIntent, runtime: HeartbeatRuntimeSnapshot, inputs: SnapshotInputs, signal: HeartbeatSignal, deps: Pick<HeartbeatDeps, "outreachDispatch" | "quietWorkflow" | "connectorExecutor" | "state" | "workspaceRoot" | "experienceWriter">): Promise<HeartbeatCycleResult>;
 export interface HeartbeatDeps {
     /** Load snapshot inputs from state-system */
     loadSnapshotInputs: () => Promise<SnapshotInputs>;
@@ -71,6 +75,8 @@ export interface HeartbeatDeps {
     workspaceRoot?: string;
     /** T2.4.1: when present, planner resolves platform-specific intents. */
     connectorRegistry?: CapabilityContractRegistry;
+    /** v7 T-V7C.C.2: when present, connector attempts write ToolExperience with triggerSource="heartbeat". */
+    experienceWriter?: ExperienceWriter;
 }
 /**
  * Ingest a heartbeat rhythm signal and drive one full decision round.

package/runtime/core/second-nature/heartbeat/heartbeat-loop.js

@@ -38,6 +38,8 @@ export async function resolveAllowedIntentResult(intent, runtime, inputs, signal
             day,
             userInterestSnapshot: inputs.userInterestSnapshot,
             workspaceRoot: deps.quietWorkflow.workspaceRoot,
+            // v7 T-V7C.C.3: pass Dream schedule port so Quiet completion triggers Dream.
+            dreamSchedulePort: deps.quietWorkflow.dreamSchedulePort,
         });
         return quietRun.result;
     }
@@ -64,6 +66,8 @@ export async function resolveAllowedIntentResult(intent, runtime, inputs, signal
             };
         }
         const decisionId = `decision:${intent.id}:${Date.now()}`;
+        // T-V7C.C.4: inject identity from EmbodiedContext into connector request (readable, no credential)
+        const platformHandle = runtime.identity?.platformHandles.find((h) => h.platformId === intent.platformId)?.handle;
         const result = await deps.connectorExecutor.executeEffect({
             platformId: intent.platformId,
             intent: toCapabilityIntent(intent),
@@ -71,6 +75,12 @@ export async function resolveAllowedIntentResult(intent, runtime, inputs, signal
             decisionId,
             intentId: intent.id,
             idempotencyKey: `idem:${intent.id}:${Date.now()}`,
+            identity: platformHandle || runtime.identity?.canonicalName
+                ? {
+                    platformHandle,
+                    canonicalName: runtime.identity?.canonicalName,
+                }
+                : undefined,
         });
         // T3.3.1: on success, map connector result to life evidence and append.
         // On failure or empty result, no evidence is fabricated — attempt audit
@@ -96,6 +106,21 @@ export async function resolveAllowedIntentResult(intent, runtime, inputs, signal
                 console.warn(`[heartbeat] evidence append failed for ${intent.platformId ?? "unknown"}: ${errorMessage}`);
             }
         }
+        // v7 T-V7C.C.2: record ToolExperience for all connector attempts in heartbeat.
+        if (deps.experienceWriter) {
+            try {
+                await deps.experienceWriter.recordExperience({
+                    connectorId: intent.platformId,
+                    capabilityId: toCapabilityIntent(intent),
+                    result,
+                    triggerSource: "heartbeat",
+                });
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                console.warn(`[heartbeat] ToolExperience record failed for ${intent.platformId ?? "unknown"}: ${errorMessage}`);
+            }
+        }
         const base = {
             scope: "rhythm",
             status: "intent_selected",

package/runtime/core/second-nature/heartbeat/runtime-snapshot.d.ts

@@ -5,6 +5,7 @@ import type { ContinuitySnapshot, ControlPlaneSourceRef } from "../types.js";
 import type { RhythmPolicy } from "../rhythm/rhythm-policy.js";
 import { type PlannerRhythmWindowSlice } from "../rhythm/planner-rhythm-window.js";
 import type { SnapshotInputs } from "./snapshot-builder.js";
+import type { AffordanceMap } from "../../../shared/types/v7-entities.js";
 export interface PlannerLifeEvidenceSlice {
     evidenceRefs: ControlPlaneSourceRef[];
     platformEventCount: number;
@@ -23,6 +24,10 @@ export interface HeartbeatRuntimeSnapshot {
     hardGuards: HardGuardDeps;
     narrativeState?: import("../../../storage/narrative/narrative-state-store.js").NarrativeState;
     relationshipMemory?: import("../../../storage/relationship/relationship-memory-store.js").RelationshipMemory;
+    /** v7: affordance map for breaker-aware guard evaluation (T-V7C.C.2). */
+    affordanceMap?: AffordanceMap;
+    /** T-V7C.C.4: identity profile for connector request identity injection. */
+    identity?: import("../../../shared/types/v7-entities.js").IdentityProfile;
 }
 export declare function buildLifeEvidenceSliceFromInputs(inputs: SnapshotInputs): PlannerLifeEvidenceSlice;
 export declare function buildHardGuardDeps(continuity: ContinuitySnapshot, inputs: SnapshotInputs): HardGuardDeps;

package/runtime/core/second-nature/heartbeat/runtime-snapshot.js

@@ -31,5 +31,14 @@ export function buildHeartbeatRuntimeSnapshot(timestamp, inputs, continuity) {
     const rhythmWindow = buildPlannerRhythmWindow(timestamp, continuity, policy);
     const lifeEvidence = buildLifeEvidenceSliceFromInputs(inputs);
     const hardGuards = buildHardGuardDeps(continuity, inputs);
-    return { continuity, lifeEvidence, rhythmWindow, hardGuards, narrativeState: inputs.narrativeState, relationshipMemory: inputs.relationshipMemory };
+    return {
+        continuity,
+        lifeEvidence,
+        rhythmWindow,
+        hardGuards,
+        narrativeState: inputs.narrativeState,
+        relationshipMemory: inputs.relationshipMemory,
+        affordanceMap: inputs.affordanceMap,
+        identity: inputs.identity,
+    };
 }

package/runtime/core/second-nature/heartbeat/snapshot-builder.d.ts

@@ -12,6 +12,7 @@ import type { DeliveryCapabilitySnapshot } from "../outreach/delivery-target.js"
 import type { UserInterestSnapshot } from "../../../storage/user-interest/types.js";
 import type { NarrativeState } from "../../../storage/narrative/narrative-state-store.js";
 import type { RelationshipMemory } from "../../../storage/relationship/relationship-memory-store.js";
+import type { AffordanceMap, IdentityProfile } from "../../../shared/types/v7-entities.js";
 export interface SnapshotInputs {
     mode: TopLevelMode;
     currentWindowId: string;
@@ -58,6 +59,10 @@ export interface SnapshotInputs {
     narrativeState?: NarrativeState;
     /** When present, planner uses relationship memory to influence outreach timing. */
     relationshipMemory?: RelationshipMemory;
+    /** v7: affordance map for breaker-aware guard evaluation (T-V7C.C.2). */
+    affordanceMap?: AffordanceMap;
+    /** T-V7C.C.4: identity profile for connector request identity injection. */
+    identity?: IdentityProfile;
 }
 /**
  * Build a ContinuitySnapshot from loaded inputs.

package/runtime/core/second-nature/orchestrator/guard-layer.js

@@ -42,6 +42,27 @@ export function evaluateHardGuards(intent, runtime) {
     if (!isSourceBacked(intent)) {
         reasons.push("missing_source_refs");
     }
+    // v7: Affordance / breaker guard (T-V7C.C.2)
+    if ((intent.effectClass === "connector_action" ||
+        intent.effectClass === "external_platform_action") &&
+        runtime.affordanceMap &&
+        intent.platformId) {
+        const platformItems = runtime.affordanceMap[intent.platformId] ?? [];
+        const match = intent.capabilityIntent
+            ? platformItems.find((i) => i.capabilityId === intent.capabilityIntent)
+            : platformItems.find((i) => i.intent === intent.summary);
+        if (match) {
+            if (match.status === "painful") {
+                reasons.push("connector_circuit_open");
+            }
+            else if (match.status === "unavailable") {
+                reasons.push("affordance_unavailable");
+            }
+        }
+        else {
+            reasons.push("affordance_unavailable");
+        }
+    }
     const key = intentFingerprint(intent);
     if (runtime.hardGuards.hasDuplicateIntent(key)) {
         reasons.push("duplicate_intent");
@@ -74,7 +95,9 @@ export function evaluateHardGuards(intent, runtime) {
     }
     const duplicate = reasons.includes("duplicate_intent");
     const cooldown = reasons.includes("outreach_cooldown");
-    if (duplicate || cooldown) {
+    const circuitOpen = reasons.includes("connector_circuit_open");
+    const affordanceUnavailable = reasons.includes("affordance_unavailable");
+    if (duplicate || cooldown || circuitOpen || affordanceUnavailable) {
         return {
             verdict: "defer",
             reasons,

package/runtime/core/second-nature/quiet/run-source-backed-quiet.d.ts

@@ -1,17 +1,37 @@
 /**
  * Quiet / reflection orchestration: empty evidence → empty_state; otherwise coverage-gated artifact (T2.3.3).
+ *
+ * v7 T-V7C.C.3: After a successful Quiet artifact write, if a DreamSchedulePort is provided,
+ * automatically trigger scheduleDream(quiet_completion). Skip reason is embedded in HeartbeatCycleResult
+ * reasons when the scheduler returns "skipped" (e.g. lock held).
  */
 import type { CandidateIntent } from "../types.js";
 import type { HeartbeatRuntimeSnapshot } from "../heartbeat/runtime-snapshot.js";
 import type { HeartbeatCycleResult } from "../heartbeat/signal.js";
 import { type QuietArtifactAck } from "../../../storage/quiet/quiet-artifact-writer.js";
 import type { UserInterestSnapshot } from "../../../storage/user-interest/types.js";
+/**
+ * Minimal port for triggering Dream after Quiet completion (T-V7C.C.3).
+ * Kept narrow so run-source-backed-quiet does not take a hard dependency on dream-scheduler.
+ */
+export interface QuietDreamSchedulePort {
+    scheduleDream(params: {
+        triggerKind: "quiet_completion";
+        runId: string;
+        traceId: string;
+    }): Promise<{
+        status: "started" | "skipped" | "queued";
+        reason?: string;
+    }>;
+}
 export interface RunSourceBackedQuietParams {
     candidate: CandidateIntent;
     runtime: HeartbeatRuntimeSnapshot;
     day: string;
     userInterestSnapshot?: UserInterestSnapshot;
     workspaceRoot?: string;
+    /** v7 T-V7C.C.3: when present, a successful Quiet artifact write auto-triggers Dream scheduling. */
+    dreamSchedulePort?: QuietDreamSchedulePort;
 }
 export interface RunSourceBackedQuietResult {
     result: HeartbeatCycleResult;

package/runtime/core/second-nature/quiet/run-source-backed-quiet.js

@@ -11,8 +11,33 @@ function toGuidanceRef(r) {
         observedAt: r.observedAt,
     };
 }
+/**
+ * v7 T-V7C.C.3: Fire-and-forget Dream schedule after successful Quiet write.
+ * Returns the schedule status reason string to embed in HeartbeatCycleResult reasons.
+ * Never throws — Dream scheduling failure must not break the Quiet cycle result.
+ */
+async function maybeScheduleDreamAfterQuiet(dreamSchedulePort, day) {
+    if (!dreamSchedulePort)
+        return undefined;
+    try {
+        const result = await dreamSchedulePort.scheduleDream({
+            triggerKind: "quiet_completion",
+            runId: `dream:quiet_completion:${day}:${Date.now()}`,
+            traceId: `trace:quiet_completion:${day}:${Date.now()}`,
+        });
+        if (result.status === "skipped") {
+            return `quiet_dream_skip:${result.reason ?? "lock_held"}`;
+        }
+        return "quiet_dream_scheduled";
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[run-source-backed-quiet] Dream schedule failed: ${msg}`);
+        return `quiet_dream_schedule_error:${msg.slice(0, 60)}`;
+    }
+}
 export async function runSourceBackedQuiet(params) {
-    const { candidate, runtime, day, userInterestSnapshot, workspaceRoot } = params;
+    const { candidate, runtime, day, userInterestSnapshot, workspaceRoot, dreamSchedulePort } = params;
     const empty = isLifeEvidenceSliceEmpty(runtime.lifeEvidence);
     if (empty) {
         const input = {
@@ -117,12 +142,17 @@ export async function runSourceBackedQuiet(params) {
         const p = await persistQuietArtifactToWorkspace(workspaceRoot, ack, reportWrite);
         persistedRelativePath = p.relativePath;
     }
+    // v7 T-V7C.C.3: After a successful source-backed Quiet write, auto-trigger Dream scheduling.
+    const dreamReason = await maybeScheduleDreamAfterQuiet(dreamSchedulePort, day);
+    const reasons = ["quiet_artifact_written", ...gq.hints.slice(0, 2)];
+    if (dreamReason)
+        reasons.push(dreamReason);
     return {
         result: {
             scope: "rhythm",
             status: "intent_selected",
             selectedIntentId: candidate.id,
-            reasons: ["quiet_artifact_written", ...gq.hints.slice(0, 2)],
+            reasons,
         },
         artifactAck: ack,
         persistedRelativePath,

package/runtime/guidance/capability-class.d.ts

@@ -0,0 +1,38 @@
+/**
+ * capability-class.ts — T-V7C.C.4R
+ *
+ * Core logic: infer CapabilityClass from capabilityIntent string prefix.
+ *
+ * CapabilityClass is the middle axis between intentKind (why) and platform (where),
+ * used by ImpulseAssembler to select appropriate behavioral impulse templates.
+ *
+ * Classification rules (prefix-based, not EffectSemanticsClass — execution layer is intentionally
+ * kept separate from expression layer):
+ *   feed.*           → consume   (browsing / reading feeds)
+ *   notification.*   → consume   (reading notifications, not interacting)
+ *   work.*           → discover  (research / task discovery)
+ *   post.*           → broadcast (publishing, primary expression)
+ *   comment.*        → interact  (replying to others' content)
+ *   message.*        → interact  (private messages / DMs)
+ *   task.*           → claim     (claiming work items)
+ *   agent.*          → null      (keepalive/internal — excluded from impulse system)
+ *   unknown/custom   → broadcast (safe default for unrecognized side-effect capabilities)
+ *
+ * Boundary:
+ * - Pure function, zero side effects.
+ * - Does NOT consult EffectSemanticsClass (execution-policy.ts) — those layers must not couple.
+ * - Custom capabilities declared by Claw without a prefix match default to "broadcast".
+ *
+ * Test coverage: tests/unit/guidance/capability-class.test.ts
+ */
+/** The expression-layer classification of a capability. */
+export type CapabilityClass = "consume" | "broadcast" | "interact" | "discover" | "claim";
+/**
+ * Infer CapabilityClass from a capabilityIntent string.
+ *
+ * Returns null for agent.* capabilities (keepalive / internal — no impulse injection).
+ * Returns "broadcast" for unrecognized custom capabilities (safe default).
+ */
+export declare function inferCapabilityClass(capabilityIntent: string): CapabilityClass | null;
+/** Map from CapabilityClass to its default intentKind-style scene, for impulse lookup fallback. */
+export declare const CAPABILITY_CLASS_SCENE_MAP: Readonly<Record<CapabilityClass, string>>;

package/runtime/guidance/capability-class.js

@@ -0,0 +1,65 @@
+/**
+ * capability-class.ts — T-V7C.C.4R
+ *
+ * Core logic: infer CapabilityClass from capabilityIntent string prefix.
+ *
+ * CapabilityClass is the middle axis between intentKind (why) and platform (where),
+ * used by ImpulseAssembler to select appropriate behavioral impulse templates.
+ *
+ * Classification rules (prefix-based, not EffectSemanticsClass — execution layer is intentionally
+ * kept separate from expression layer):
+ *   feed.*           → consume   (browsing / reading feeds)
+ *   notification.*   → consume   (reading notifications, not interacting)
+ *   work.*           → discover  (research / task discovery)
+ *   post.*           → broadcast (publishing, primary expression)
+ *   comment.*        → interact  (replying to others' content)
+ *   message.*        → interact  (private messages / DMs)
+ *   task.*           → claim     (claiming work items)
+ *   agent.*          → null      (keepalive/internal — excluded from impulse system)
+ *   unknown/custom   → broadcast (safe default for unrecognized side-effect capabilities)
+ *
+ * Boundary:
+ * - Pure function, zero side effects.
+ * - Does NOT consult EffectSemanticsClass (execution-policy.ts) — those layers must not couple.
+ * - Custom capabilities declared by Claw without a prefix match default to "broadcast".
+ *
+ * Test coverage: tests/unit/guidance/capability-class.test.ts
+ */
+/**
+ * Infer CapabilityClass from a capabilityIntent string.
+ *
+ * Returns null for agent.* capabilities (keepalive / internal — no impulse injection).
+ * Returns "broadcast" for unrecognized custom capabilities (safe default).
+ */
+export function inferCapabilityClass(capabilityIntent) {
+    if (!capabilityIntent || typeof capabilityIntent !== "string")
+        return null;
+    const prefix = capabilityIntent.split(".")[0]?.toLowerCase() ?? "";
+    switch (prefix) {
+        case "agent":
+            return null; // Keepalive/internal: excluded from impulse system entirely
+        case "feed":
+        case "notification":
+            return "consume";
+        case "work":
+            return "discover";
+        case "post":
+            return "broadcast";
+        case "comment":
+        case "message":
+            return "interact";
+        case "task":
+            return "claim";
+        default:
+            // Custom or unrecognized capability — default to broadcast (outward expression)
+            return "broadcast";
+    }
+}
+/** Map from CapabilityClass to its default intentKind-style scene, for impulse lookup fallback. */
+export const CAPABILITY_CLASS_SCENE_MAP = {
+    consume: "explore",
+    discover: "explore",
+    broadcast: "social",
+    interact: "reply",
+    claim: "work",
+};

package/runtime/guidance/guidance-assembler.d.ts

@@ -1,5 +1,7 @@
+import { type PlatformImpulsePort } from "./impulse-assembler.js";
 import type { GuidancePayload, GuidanceUnavailable, PersonaCandidate, SceneContext } from "./types.js";
 export declare function assembleGuidance(input: {
     sceneContext: SceneContext | null | undefined;
     personaCandidates?: PersonaCandidate[];
+    platformImpulsePort?: PlatformImpulsePort;
 }): Promise<GuidancePayload | GuidanceUnavailable>;

package/runtime/guidance/guidance-assembler.js

@@ -1,7 +1,8 @@
 import { buildMinimalGuidanceFallback } from "./fallback.js";
 import { buildOutputGuard } from "./output-guard.js";
 import { selectPersonaSnippets } from "./persona-selection.js";
-import { getBaselineAtmosphereTemplate, getImpulseTemplate } from "./template-registry.js";
+import { getBaselineAtmosphereTemplate } from "./template-registry.js";
+import { assembleImpulse } from "./impulse-assembler.js";
 async function buildAtmosphere(sceneContext) {
     const template = getBaselineAtmosphereTemplate();
     return {
@@ -12,11 +13,21 @@ async function buildAtmosphere(sceneContext) {
         reviewStatus: template.reviewStatus,
     };
 }
-async function selectImpulses(sceneContext) {
+/**
+ * Select impulses using the dual-axis capabilityClass assembler (T-V7C.C.4R).
+ *
+ * Fallback chain: platform-specific → capabilityClass preset → intentKind → []
+ */
+async function selectImpulses(sceneContext, deps) {
     if (sceneContext.sceneType === "explain" || sceneContext.sceneType === "user_reply") {
         return [];
     }
-    return [getImpulseTemplate(sceneContext.sceneType)];
+    const result = await assembleImpulse({
+        sceneType: sceneContext.sceneType,
+        capabilityIntent: sceneContext.capabilityIntent,
+        platformId: sceneContext.platformId,
+    }, deps);
+    return result.impulse ? [result.impulse] : [];
 }
 export async function assembleGuidance(input) {
     if (!input.sceneContext) {
@@ -26,10 +37,11 @@ export async function assembleGuidance(input) {
         };
     }
     const sceneContext = input.sceneContext;
+    const deps = { platformImpulsePort: input.platformImpulsePort };
     try {
         const [atmosphere, impulses] = await Promise.all([
             buildAtmosphere(sceneContext),
-            selectImpulses(sceneContext),
+            selectImpulses(sceneContext, deps),
         ]);
         const personaDecision = selectPersonaSnippets({
             sceneContext,

package/runtime/guidance/guidance-draft-service.js

@@ -19,16 +19,16 @@ const SCENE_KINDS = [
     "reconnect",
 ];
 function buildDraftText(request, claims) {
-    const anchor = claims.map((c) => c.text).join("; ");
+    const anchor = claims.map((c) => c.text).join("；");
     switch (request.sceneKind) {
         case "outreach":
-            return `Hi there — wanted to share something that came up: ${anchor}`;
+            return `有件事想跟你分享，正好碰到了：${anchor}`;
         case "follow_up":
-            return `Following up on what we talked about: ${anchor}`;
+            return `接着上次聊的说一下：${anchor}`;
         case "reconnect":
-            return `It's been a while — here's what caught my attention: ${anchor}`;
+            return `好久不见，最近有个东西让我想到你：${anchor}`;
         default:
-            return `Draft for ${request.sceneKind}: ${anchor}`;
+            return `关于 ${request.sceneKind}：${anchor}`;
     }
 }
 export async function generateGuidanceDraft(request, deps) {

package/runtime/guidance/impulse-assembler.d.ts

@@ -0,0 +1,71 @@
+/**
+ * impulse-assembler.ts — T-V7C.C.4R
+ *
+ * Core logic: three-level fallback impulse selection.
+ *
+ * Priority chain (highest → lowest):
+ *   1. platform-specific impulse  — Claw-defined per platformId, loaded from workspace
+ *   2. capabilityClass preset     — derived from capabilityIntent prefix via inferCapabilityClass
+ *   3. intentKind fallback        — existing scene type impulse (social/outreach/reply/quiet)
+ *   4. null                       — no impulse (baseline atmosphere still applies)
+ *
+ * Exclusions:
+ *   - agent.* capabilities → null always (keepalive/internal, not an expression action)
+ *   - explore/work capabilityClass impulses → approved and active (T-V7C.C.4R review complete)
+ *
+ * Boundary:
+ * - Pure function composition; no I/O except the optional platformImpulsePort.
+ * - Does NOT write state or emit events.
+ * - SceneContext is enriched with capabilityIntent + platformId as optional fields
+ *   to carry the dual-axis context without breaking existing SceneContext consumers.
+ *
+ * Test coverage: tests/unit/guidance/impulse-assembler.test.ts
+ */
+import type { ImpulseBlock, GuidanceSceneType } from "./types.js";
+import { type CapabilityClass } from "./capability-class.js";
+/** Extended scene context carrying dual-axis impulse selection inputs. */
+export interface ImpulseSelectionContext {
+    /** The intent kind (why) — maps to intentKind fallback impulse. */
+    sceneType: GuidanceSceneType;
+    /** The capability being executed (what physical form). e.g. "post.publish", "feed.read" */
+    capabilityIntent?: string;
+    /** The platform being targeted. Used for platform-specific impulse lookup. */
+    platformId?: string;
+}
+/**
+ * Port for loading platform-specific impulse overrides.
+ * Claw implements this by writing impulse files to the workspace.
+ * When absent, the assembler skips platform-specific lookup gracefully.
+ */
+export interface PlatformImpulsePort {
+    /**
+     * Load a platform-specific impulse for the given platformId + capabilityClass.
+     * Returns null when no override is defined.
+     */
+    loadPlatformImpulse(input: {
+        platformId: string;
+        capabilityClass: CapabilityClass;
+    }): Promise<ImpulseBlock | null>;
+}
+export interface ImpulseAssemblerResult {
+    /** The selected impulse, or null if no applicable impulse exists. */
+    impulse: ImpulseBlock | null;
+    /** Which level of the fallback chain was used. */
+    source: "platform_specific" | "capability_class" | "intent_kind" | "none";
+    /** The inferred capability class (null for agent.* or unknown intent). */
+    capabilityClass: CapabilityClass | null;
+}
+/**
+ * Select the most specific impulse for a given scene + capability context.
+ *
+ * Fallback chain:
+ *   platform-specific → capabilityClass preset → intentKind → null
+ */
+export declare function assembleImpulse(ctx: ImpulseSelectionContext, deps: {
+    platformImpulsePort?: PlatformImpulsePort;
+}): Promise<ImpulseAssemblerResult>;
+/**
+ * Synchronous variant for contexts where capabilityClass + intentKind are sufficient
+ * and no platform-specific port is needed (e.g. guidance_payload ops command preview).
+ */
+export declare function assembleImpulseSync(ctx: ImpulseSelectionContext): ImpulseAssemblerResult;

package/runtime/guidance/impulse-assembler.js

@@ -0,0 +1,103 @@
+/**
+ * impulse-assembler.ts — T-V7C.C.4R
+ *
+ * Core logic: three-level fallback impulse selection.
+ *
+ * Priority chain (highest → lowest):
+ *   1. platform-specific impulse  — Claw-defined per platformId, loaded from workspace
+ *   2. capabilityClass preset     — derived from capabilityIntent prefix via inferCapabilityClass
+ *   3. intentKind fallback        — existing scene type impulse (social/outreach/reply/quiet)
+ *   4. null                       — no impulse (baseline atmosphere still applies)
+ *
+ * Exclusions:
+ *   - agent.* capabilities → null always (keepalive/internal, not an expression action)
+ *   - explore/work capabilityClass impulses → approved and active (T-V7C.C.4R review complete)
+ *
+ * Boundary:
+ * - Pure function composition; no I/O except the optional platformImpulsePort.
+ * - Does NOT write state or emit events.
+ * - SceneContext is enriched with capabilityIntent + platformId as optional fields
+ *   to carry the dual-axis context without breaking existing SceneContext consumers.
+ *
+ * Test coverage: tests/unit/guidance/impulse-assembler.test.ts
+ */
+import { inferCapabilityClass, CAPABILITY_CLASS_SCENE_MAP, } from "./capability-class.js";
+import { getImpulseTemplate, getCapabilityClassImpulseTemplate, } from "./template-registry.js";
+// ─── Core assembly logic ──────────────────────────────────────────────────────
+/**
+ * Select the most specific impulse for a given scene + capability context.
+ *
+ * Fallback chain:
+ *   platform-specific → capabilityClass preset → intentKind → null
+ */
+export async function assembleImpulse(ctx, deps) {
+    // Infer capability class from capabilityIntent prefix
+    const capabilityClass = ctx.capabilityIntent
+        ? inferCapabilityClass(ctx.capabilityIntent)
+        : null;
+    // agent.* → excluded entirely
+    if (ctx.capabilityIntent && inferCapabilityClass(ctx.capabilityIntent) === null &&
+        ctx.capabilityIntent.startsWith("agent.")) {
+        return { impulse: null, source: "none", capabilityClass: null };
+    }
+    // ── Level 1: platform-specific ──────────────────────────────────────────────
+    if (ctx.platformId && capabilityClass && deps.platformImpulsePort) {
+        try {
+            const platformImpulse = await deps.platformImpulsePort.loadPlatformImpulse({
+                platformId: ctx.platformId,
+                capabilityClass,
+            });
+            if (platformImpulse) {
+                return { impulse: platformImpulse, source: "platform_specific", capabilityClass };
+            }
+        }
+        catch {
+            // Port failure → fall through gracefully
+        }
+    }
+    // ── Level 2: capabilityClass preset ─────────────────────────────────────────
+    if (capabilityClass) {
+        const ccImpulseKind = CAPABILITY_CLASS_SCENE_MAP[capabilityClass];
+        const ccImpulse = getCapabilityClassImpulseTemplate(ccImpulseKind);
+        if (ccImpulse) {
+            return { impulse: ccImpulse, source: "capability_class", capabilityClass };
+        }
+        // explore/work are pending review → fall through to intentKind
+    }
+    // ── Level 3: intentKind fallback ─────────────────────────────────────────────
+    const sceneType = ctx.sceneType;
+    if (sceneType !== "explain" && sceneType !== "user_reply") {
+        const intentImpulse = getImpulseTemplate(sceneType);
+        return { impulse: intentImpulse, source: "intent_kind", capabilityClass };
+    }
+    // ── Level 4: no impulse ───────────────────────────────────────────────────────
+    return { impulse: null, source: "none", capabilityClass };
+}
+/**
+ * Synchronous variant for contexts where capabilityClass + intentKind are sufficient
+ * and no platform-specific port is needed (e.g. guidance_payload ops command preview).
+ */
+export function assembleImpulseSync(ctx) {
+    const capabilityClass = ctx.capabilityIntent
+        ? inferCapabilityClass(ctx.capabilityIntent)
+        : null;
+    // agent.* excluded
+    if (ctx.capabilityIntent?.startsWith("agent.")) {
+        return { impulse: null, source: "none", capabilityClass: null };
+    }
+    // capabilityClass preset (sync — no platform port available)
+    if (capabilityClass) {
+        const ccImpulseKind = CAPABILITY_CLASS_SCENE_MAP[capabilityClass];
+        const ccImpulse = getCapabilityClassImpulseTemplate(ccImpulseKind);
+        if (ccImpulse) {
+            return { impulse: ccImpulse, source: "capability_class", capabilityClass };
+        }
+    }
+    // intentKind fallback
+    const sceneType = ctx.sceneType;
+    if (sceneType !== "explain" && sceneType !== "user_reply") {
+        const intentImpulse = getImpulseTemplate(sceneType);
+        return { impulse: intentImpulse, source: "intent_kind", capabilityClass };
+    }
+    return { impulse: null, source: "none", capabilityClass };
+}

package/runtime/guidance/index.d.ts

@@ -5,6 +5,8 @@ export * from "./output-guard.js";
 export * from "./fallback.js";
 export * from "./template-registry.js";
 export * from "./review-workflow.js";
+export * from "./capability-class.js";
+export * from "./impulse-assembler.js";
 export * from "./guidance-assembler.js";
 export * from "./outreach-draft-schema.js";
 export * from "./draft-outreach-message.js";

package/runtime/guidance/index.js

@@ -5,6 +5,8 @@ export * from "./output-guard.js";
 export * from "./fallback.js";
 export * from "./template-registry.js";
 export * from "./review-workflow.js";
+export * from "./capability-class.js";
+export * from "./impulse-assembler.js";
 export * from "./guidance-assembler.js";
 export * from "./outreach-draft-schema.js";
 export * from "./draft-outreach-message.js";