@captain_z/zsk 1.8.3 → 1.8.4

package/dist/core/profile-bundle-installation.js

@@ -0,0 +1,170 @@
+import { readFile, readdir } from "node:fs/promises";
+import { basename, dirname, join, relative } from "node:path";
+import { expandCapabilityFilters, hasCapabilityFilter, } from "./capabilities.js";
+import { install, skillRelPath } from "./installer.js";
+import { buildManifest, sha256File, } from "./manifest.js";
+import { loadSkill } from "./skills.js";
+export const DEFAULT_PROFILE_BUNDLE = "zsk-sdlc";
+export async function installProfileBundle(plan) {
+    return install(plan);
+}
+export function isProfileBundleMaintenanceRun(args) {
+    return args.targetProvided && args.hasManifest && !args.hasExplicitPicks;
+}
+export function resolveProfileInstallMode(args) {
+    if (!args.hasManifest)
+        return "new";
+    if (args.hasExplicitPicks)
+        return "append";
+    return args.requestedAction ?? "exit";
+}
+export function buildProfileBundleOptions(bundles) {
+    return profileBundleEntries(bundles)
+        .map(([name, bundle]) => ({
+        value: name,
+        label: bundle.label || name,
+        hint: buildProfileBundleSummary(bundle.skills),
+    }));
+}
+export function resolveProfileBundleChoices(selectedBundleNames, bundles, availableSkills) {
+    const skills = uniqueStrings(selectedBundleNames.flatMap((name) => {
+        const bundle = bundles[name];
+        return bundle ? profileBundleToAvailableSkills(bundle, availableSkills) : [];
+    }));
+    return {
+        skills,
+        bundle: selectedBundleNames.length === 1
+            ? inferProfileBundleName(selectedBundleNames[0] ?? null, skills, bundles, availableSkills)
+            : null,
+    };
+}
+export function resolveCapabilityProfileSelection(filters, availableSkills) {
+    const matched = expandCapabilityFilters(filters.skill ?? [], availableSkills);
+    if (!hasCapabilityFilter(filters))
+        return null;
+    return { skills: matched, bundle: null };
+}
+export function resolveProfileBundlePatternSelection(args) {
+    const { bundles, availableSkills, bundlePatterns, skillPatterns } = args;
+    const matched = expandCapabilityFilters(skillPatterns, availableSkills);
+    const selected = uniqueStrings([
+        ...bundlePatterns.flatMap((name) => {
+            const bundle = bundles[name];
+            return bundle ? profileBundleToAvailableSkills(bundle, availableSkills) : [];
+        }),
+        ...matched,
+    ]);
+    return {
+        skills: selected,
+        bundle: bundlePatterns.length === 1
+            ? inferProfileBundleName(bundlePatterns[0] ?? null, selected, bundles, availableSkills)
+            : null,
+    };
+}
+export function inferProfileBundleName(selectedBundleName, selectedSkills, bundles, availableSkills) {
+    if (!selectedBundleName)
+        return null;
+    const bundle = bundles[selectedBundleName];
+    if (!bundle)
+        return null;
+    const expected = profileBundleToAvailableSkills(bundle, availableSkills);
+    return sameMembers(selectedSkills, expected) ? selectedBundleName : null;
+}
+export function profileBundleToAvailableSkills(bundle, availableSkills) {
+    const set = new Set(availableSkills);
+    return bundle.skills.filter((skill) => set.has(skill));
+}
+export function inferProfileBundleInstallLayout(targetPath, format) {
+    if (format === "claude-plugin")
+        return "claude-plugin";
+    if (format === "flat")
+        return "flat";
+    const base = basename(targetPath);
+    return base === ".claude-plugin" || base === "claude-plugin"
+        ? "claude-plugin"
+        : "flat";
+}
+export async function buildProfileBundleManifestRecords(skillNames, targetPath, layout, zskVersion) {
+    const out = [];
+    for (const name of skillNames) {
+        try {
+            const skill = await loadSkill(name);
+            const relPath = skillRelPath(skill, layout);
+            const buf = await readFile(join(targetPath, relPath));
+            const skillRoot = dirname(relPath);
+            out.push({
+                name,
+                version: zskVersion,
+                sha256: sha256File(buf),
+                relPath,
+                files: await buildOwnedFileRecords(targetPath, skillRoot),
+            });
+        }
+        catch {
+            // The skill may have been skipped by conflict policy; omit it from the manifest.
+        }
+    }
+    return out;
+}
+export function buildProfileBundleManifest(params) {
+    return buildManifest(params);
+}
+export function mergeProfileBundleManifestSkills(existing, fresh, currentInstallableNames) {
+    const map = new Map();
+    for (const entry of existing) {
+        if (currentInstallableNames.has(entry.name))
+            map.set(entry.name, entry);
+    }
+    for (const entry of fresh)
+        map.set(entry.name, entry);
+    return [...map.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+function profileBundleEntries(bundles) {
+    return Object.entries(bundles)
+        .filter(([, bundle]) => bundle.skills.length > 0)
+        .sort(([leftName], [rightName]) => {
+        if (leftName === DEFAULT_PROFILE_BUNDLE)
+            return -1;
+        if (rightName === DEFAULT_PROFILE_BUNDLE)
+            return 1;
+        return leftName.localeCompare(rightName);
+    });
+}
+function buildProfileBundleSummary(skills) {
+    const preview = skills.slice(0, 3).join(", ");
+    const suffix = skills.length > 3 ? ", ..." : "";
+    return `${skills.length} 个 · ${preview}${suffix}`;
+}
+async function buildOwnedFileRecords(targetPath, skillRoot) {
+    const absRoot = join(targetPath, skillRoot);
+    const files = await walkFiles(absRoot);
+    const records = await Promise.all(files.map(async (absPath) => ({
+        relPath: relative(targetPath, absPath),
+        sha256: sha256File(await readFile(absPath)),
+    })));
+    return records.sort((left, right) => left.relPath.localeCompare(right.relPath));
+}
+async function walkFiles(dir) {
+    const out = [];
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...(await walkFiles(path)));
+        }
+        else if (entry.isFile()) {
+            out.push(path);
+        }
+    }
+    return out;
+}
+function sameMembers(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const rightSet = new Set(right);
+    return left.every((value) => rightSet.has(value));
+}
+function uniqueStrings(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+//# sourceMappingURL=profile-bundle-installation.js.map

package/dist/core/profile-bundle-installation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-bundle-installation.js","sourceRoot":"","sources":["../../src/core/profile-bundle-installation.ts"],"names":[],"mappings":"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"}

package/dist/core/source-snapshot-adapters.d.ts

@@ -0,0 +1,59 @@
+import { type ProjectConfig, type SourceConfig, type SourceEntry } from "./config.js";
+import { type OriginInference } from "./origin-detection.js";
+export type PrepareSyncOptions = {
+    source?: string;
+    all?: boolean;
+    allowNetwork?: boolean;
+    authState?: string;
+    authProfile?: string;
+    browser?: boolean;
+    dryRun?: boolean;
+    runId?: string;
+};
+export type PrepareSyncStatus = "materialized" | "metadata-only" | "blocked-auth" | "source-gap" | "skipped" | "failed";
+export type PrepareSyncResult = {
+    envelopeVersion?: 1;
+    sourceKey: string;
+    sourcePath: string;
+    rawLane?: string;
+    provider?: string;
+    adapter?: string;
+    strategy: string;
+    status: PrepareSyncStatus;
+    origin?: string;
+    resolvedOrigin?: string;
+    contentType?: string;
+    snapshot?: string;
+    snapshotHash?: string;
+    previousSnapshotHash?: string;
+    metadata?: Record<string, unknown>;
+    changed: boolean;
+    reason: string;
+    validation: Record<string, "pass" | "fail" | "skipped">;
+};
+export type PrepareSyncBase = Omit<PrepareSyncResult, "strategy" | "status" | "changed" | "reason" | "validation">;
+export type SourceSnapshotProviderAdapter = "confluence" | "jira" | "gitlab" | "design-source";
+export type SourceSnapshotContext = {
+    target: string;
+    config: ProjectConfig;
+    entry: SourceEntry;
+    source: SourceConfig;
+    origin: OriginInference;
+    opts: PrepareSyncOptions;
+    snapshot: string;
+    snapshotPath: string;
+    previousSnapshotHash?: string;
+    base: PrepareSyncBase;
+};
+export type SourceSnapshotAdapterHandlers = {
+    dryRun: (context: SourceSnapshotContext) => Promise<PrepareSyncResult> | PrepareSyncResult;
+    local: (context: SourceSnapshotContext) => Promise<PrepareSyncResult>;
+    provider: (context: SourceSnapshotContext, adapter: SourceSnapshotProviderAdapter) => Promise<PrepareSyncResult | null>;
+    repository: (context: SourceSnapshotContext) => Promise<PrepareSyncResult>;
+    url: (context: SourceSnapshotContext) => Promise<PrepareSyncResult>;
+    providerManaged: (context: SourceSnapshotContext) => Promise<PrepareSyncResult> | PrepareSyncResult;
+};
+export declare function createSourceSnapshotContext(target: string, config: ProjectConfig, entry: SourceEntry, opts: PrepareSyncOptions, previousSnapshotHashFor: (snapshotPath: string) => Promise<string | undefined>): Promise<SourceSnapshotContext>;
+export declare function acquireSourceSnapshot(context: SourceSnapshotContext, handlers: SourceSnapshotAdapterHandlers): Promise<PrepareSyncResult>;
+export declare function selectSourceSnapshotProviderAdapter(source: SourceConfig, origin: OriginInference): SourceSnapshotProviderAdapter | undefined;
+export declare function chooseSourceSnapshotStrategy(method: string): string;

package/dist/core/source-snapshot-adapters.js

@@ -0,0 +1,82 @@
+import { resolve } from "node:path";
+import { resolveSourceSnapshot, } from "./config.js";
+import { inferSourceOrigin } from "./origin-detection.js";
+export async function createSourceSnapshotContext(target, config, entry, opts, previousSnapshotHashFor) {
+    const source = entry.source;
+    const origin = inferSourceOrigin(source);
+    const snapshot = resolveSourceSnapshot(config, entry);
+    const snapshotPath = resolve(target, snapshot);
+    const previousSnapshotHash = await previousSnapshotHashFor(snapshotPath);
+    const base = {
+        envelopeVersion: 1,
+        sourceKey: entry.id,
+        sourcePath: entry.path,
+        rawLane: entry.rawLane,
+        provider: origin.provider,
+        origin: origin.ref,
+        snapshot,
+        previousSnapshotHash,
+    };
+    return {
+        target,
+        config,
+        entry,
+        source,
+        origin,
+        opts,
+        snapshot,
+        snapshotPath,
+        previousSnapshotHash,
+        base,
+    };
+}
+export async function acquireSourceSnapshot(context, handlers) {
+    if (context.opts.dryRun)
+        return handlers.dryRun(context);
+    if (context.origin.method === "local")
+        return handlers.local(context);
+    const providerAdapter = selectSourceSnapshotProviderAdapter(context.source, context.origin);
+    if (providerAdapter) {
+        const result = await handlers.provider(context, providerAdapter);
+        if (result)
+            return result;
+    }
+    if (context.origin.method === "repository")
+        return handlers.repository(context);
+    if (context.origin.method === "url")
+        return handlers.url(context);
+    return handlers.providerManaged(context);
+}
+export function selectSourceSnapshotProviderAdapter(source, origin) {
+    const keys = [
+        origin.provider,
+        origin.kind,
+        source.origin?.provider,
+        source.origin?.kind,
+        source.kind,
+        source.type,
+    ].map((value) => normalizeAdapterKey(typeof value === "string" ? value : undefined));
+    if (keys.some((value) => value.includes("confluence")))
+        return "confluence";
+    if (keys.some((value) => value.includes("jira")))
+        return "jira";
+    if (keys.some((value) => value.includes("gitlab")))
+        return "gitlab";
+    if (keys.some((value) => ["figma", "modao", "mastergo", "design", "design-asset", "design-source"].includes(value))) {
+        return "design-source";
+    }
+    return undefined;
+}
+export function chooseSourceSnapshotStrategy(method) {
+    if (method === "local")
+        return "local-copy-structured-markdown";
+    if (method === "repository")
+        return "repository-metadata-only";
+    if (method === "url")
+        return "playwright-auth-or-direct-fetch";
+    return "confirm-acquisition-method";
+}
+function normalizeAdapterKey(value) {
+    return value?.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") ?? "";
+}
+//# sourceMappingURL=source-snapshot-adapters.js.map

package/dist/core/source-snapshot-adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-snapshot-adapters.js","sourceRoot":"","sources":["../../src/core/source-snapshot-adapters.ts"],"names":[],"mappings":"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"}

package/dist/core/staffing-plan.js

@@ -17,6 +17,7 @@ const PREPROPOSAL_ROLE_NAMES = [
     "planner",
     "ux-specialist",
     "design-specialist",
+    "frontend-engineer",
     "architect",
     "qa-engineer",
     "researcher",
@@ -69,14 +70,14 @@ const BUILTIN_ROLE_POOL = {
         }),
         rolePoolEntry("frontend-engineer", {
             subagentType: "executor",
-            stages: ["design"],
+            stages: ["preproposal", "design"],
             lanes: ["frontend", "web", "client", "mobile"],
             activation: "when frontend implementation, routing, state, or UI integration is in scope",
             reason: "map UI implementation, routing, state, and component integration risk",
         }),
         rolePoolEntry("design-specialist", {
             subagentType: "designer",
-            stages: ["prepare", "preproposal", "design"],
+            stages: ["prepare", "preproposal"],
             lanes: ["design", "ui", "visual"],
             activation: "when design, UI, visual, prototype, or asset sources are configured",
             reason: "inspect design assets, screens, visual states, and design-source gaps",
@@ -173,10 +174,12 @@ const ROLE_CONTRACTS = {
             ".zsk/evidence/{scope}/{run}/integration-summary.md",
             ".zsk/raws/manifest.json when prepare snapshots change",
             ".zsk/raws/manifest.json and .zsk/raws/index.md when preproposal raw resources change",
+            ".zsk/raws/prepare/product/{topic}/intake-clarity.md when running preproposal",
             ".zsk/evidence/preproposal/{run}/readiness-review.md when running preproposal",
         ],
         evidenceRequired: [
             "integrated lane status with pass/blocker/waived reason for each role",
+            "source-discoverable questions answered before user clarification when running preproposal",
             "confirmation that shared/global artifacts were updated only after lane validation",
         ],
         forbiddenDecisions: [
@@ -190,10 +193,11 @@ const ROLE_CONTRACTS = {
         doesNotOwn: ["backend implementation details", "technical feasibility signoff without architect/engineer evidence"],
         outputs: [
             ".zsk/evidence/{scope}/{run}/product-source-report.md",
+            ".zsk/raws/prepare/product/{topic}/intake-clarity.md when running preproposal",
             ".zsk/raws/prepare/product/{topic}/product-brief.md when running preproposal",
             ".zsk/evidence/preproposal/{run}/checkpoint-product-review.md when running preproposal",
         ],
-        evidenceRequired: ["requirement/source IDs or paths behind each product claim", "open requirement gaps and acceptance risks", "product checkpoint verdict before roadmap/decomposition when running preproposal"],
+        evidenceRequired: ["requirement/source IDs or paths behind each product claim", "accepted clarifications, inferred assumptions, and one blocking question when running preproposal", "open requirement gaps and acceptance risks", "product checkpoint verdict before roadmap/decomposition when running preproposal"],
         forbiddenDecisions: ["Do not rewrite technical design or implementation ownership.", "Do not turn weak/inferred evidence into accepted requirements."],
         stopCondition: "Product facts, gaps, and acceptance risks are explicit and handed to lead-integrator.",
     },
@@ -229,33 +233,36 @@ const ROLE_CONTRACTS = {
         stopCondition: "Backend facts and gaps are reported with source references and no shared artifact edits pending.",
     },
     "frontend-engineer": {
-        owns: ["UI implementation, routing, state, component integration, and frontend framework constraints"],
+        owns: ["UI implementation, routing, state, page/module-to-code component mapping, component integration, and frontend framework constraints"],
         doesNotOwn: ["source-of-truth product decisions", "backend/API correctness signoff"],
         outputs: [".zsk/evidence/{scope}/{run}/frontend-impact-report.md"],
-        evidenceRequired: ["component/route/state file references", "UI implementation risks and validation hooks"],
+        evidenceRequired: ["component/route/state file references", "page/module-to-code mapping coverage", "UI implementation risks and validation hooks"],
         forbiddenDecisions: ["Do not reinterpret acceptance criteria without product-owner handoff.", "Do not approve API behavior without backend evidence."],
         stopCondition: "Frontend impact and validation needs are clear for lead-integrator.",
     },
     "design-specialist": {
-        owns: ["design assets, visual constraints, screen/state inventory, and design snapshot validation"],
+        owns: ["design assets, visual constraints, screen/state inventory, provider source maps, and design snapshot validation"],
         doesNotOwn: ["backend/API correctness", "final product scope acceptance"],
         outputs: [
             ".zsk/evidence/{scope}/{run}/design-asset-report.md",
             ".zsk/raws/prepare/design/{topic}/design-source-needs.md when running preproposal",
+            ".zsk/raws/prepare/design/{topic}/design-source-map.md when provider-backed design sources are used",
         ],
-        evidenceRequired: ["design/prototype source references", "screen/state map and missing asset list"],
+        evidenceRequired: ["design/prototype source references", "screen/state map, provider source coverage, and missing asset list"],
         forbiddenDecisions: ["Do not infer implementation truth from design assets.", "Do not store auth state or exported private assets outside declared scope."],
         stopCondition: "Design assets are mapped or blocked with provider/auth evidence.",
     },
     "ux-specialist": {
-        owns: ["user flows, interaction constraints, usability risks, and UX source validation"],
+        owns: ["user flows, interaction handoff, interaction constraints, usability risks, and UX source validation"],
         doesNotOwn: ["backend/API correctness", "business priority decisions"],
         outputs: [
             ".zsk/evidence/{scope}/{run}/ux-source-report.md",
             ".zsk/raws/prepare/ux/{topic}/ux-readiness.md when running preproposal",
+            ".zsk/raws/prepare/ux/{topic}/interaction-handoff.md when UI, UX, or design-source interaction is triggered",
             ".zsk/evidence/preproposal/{run}/checkpoint-ux-review.md when running preproposal",
+            ".zsk/evidence/preproposal/{run}/checkpoint-interaction-review.md when interaction handoff is triggered",
         ],
-        evidenceRequired: ["flow/source references", "usability risks and unresolved interaction questions"],
+        evidenceRequired: ["flow/source references", "AI brief draft status", "page/module interaction detail coverage", "interaction/state/a11y coverage", "usability risks and unresolved interaction questions"],
         forbiddenDecisions: ["Do not approve product scope or technical design alone.", "Do not resolve UX/product conflicts silently."],
         stopCondition: "UX facts, questions, and risks are ready for lead integration.",
     },
@@ -464,7 +471,7 @@ function seedFromRolePool(role, entries, overrides = {}) {
         reason: overrides.reason ?? role.reason ?? `configured ${role.role} role`,
         entries,
         activation: overrides.activation ?? role.activation,
-        extraInputs: role.extraInputs,
+        extraInputs: unique([...(role.extraInputs ?? []), ...(overrides.extraInputs ?? [])]),
         writeScope: unique([...(role.writeScope ?? []), ...(overrides.writeScope ?? [])]),
         outputs: unique([...(role.outputs ?? []), ...(overrides.outputs ?? [])]),
         evidenceRequired: unique([...(role.evidenceRequired ?? []), ...(overrides.evidenceRequired ?? [])]),
@@ -559,7 +566,7 @@ export function buildStaffingPlan(target, config, opts = {}, rolePool = BUILTIN_
     const reviewMode = reviewModeForReviewTarget(reviewTarget);
     const timeoutPolicy = packetTimeoutPolicyFromConfig(config);
     const entries = flattenProjectSources(config.sources);
-    const seeds = seedRoles(stage, skill, entries, rolePool, reviewMode);
+    const seeds = seedRoles(stage, skill, entries, rolePool, reviewMode, opts.module);
     const orchestration = buildOrchestrationPlan(surface, stage, entries, seeds, config);
     const roles = seeds.map((seed) => buildRole(seed, stage, skill, orchestration, config));
     const dir = resolve(target, getWorkspacePath(config, "evidenceRoot"), "dispatch", runId);
@@ -660,7 +667,7 @@ function markPacketStale(packet, now) {
         blocker: "No heartbeat was recorded before the packet deadline; route this lane through leader-sequential fallback or re-emit with a new packet.",
     };
 }
-function seedRoles(stage, skill, entries, rolePool, reviewMode) {
+function seedRoles(stage, skill, entries, rolePool, reviewMode, module) {
     const seeds = new Map();
     const poolRoles = Object.values(rolePool.roles);
     for (const role of poolRoles) {
@@ -706,13 +713,26 @@ function seedRoles(stage, skill, entries, rolePool, reviewMode) {
         }
     }
     if (stage === "preproposal" || skill === "preproposal") {
+        const topic = module ?? "{topic}";
+        const moduleInputs = module
+            ? [
+                `.zsk/modules/${module}/module.yaml`,
+                `.zsk/modules/${module}/CONTEXT.md`,
+                `.zsk/modules/${module}/proposal.md when present`,
+                `.zsk/modules/${module}/spec.md when present`,
+                `.zsk/modules/${module}/design.md when present`,
+                `.zsk/modules/${module}/tasks.md when present`,
+            ]
+            : [];
         for (const roleName of PREPROPOSAL_ROLE_NAMES) {
             const role = rolePool.roles[roleName];
             if (!role)
                 continue;
             addSeed(seeds, seedFromRolePool(role, [], {
                 activation: "required for preproposal product/roadmap/UX/readiness checkpoint coverage",
-                reason: role.reason || "produce and review preproposal raw resources before formal proposal",
+                reason: module
+                    ? role.reason || `produce and review module-scoped preproposal raw resources for ${module} before formal proposal`
+                    : role.reason || "produce and review preproposal raw resources before formal proposal",
                 writeScope: [
                     ".zsk/raws/prepare/product/**",
                     ".zsk/raws/prepare/ux/**",
@@ -723,23 +743,37 @@ function seedRoles(stage, skill, entries, rolePool, reviewMode) {
                     ...role.writeScope,
                 ],
                 outputs: [
-                    ".zsk/raws/prepare/product/{topic}/product-brief.md",
-                    ".zsk/raws/prepare/product/{topic}/roadmap.md",
-                    ".zsk/raws/prepare/ux/{topic}/ux-readiness.md",
-                    ".zsk/raws/prepare/design/{topic}/design-source-needs.md",
+                    `.zsk/raws/prepare/product/${topic}/intake-clarity.md`,
+                    `.zsk/raws/prepare/product/${topic}/product-brief.md`,
+                    `.zsk/raws/prepare/product/${topic}/roadmap.md`,
+                    `.zsk/raws/prepare/ux/${topic}/ux-readiness.md`,
+                    `.zsk/raws/prepare/ux/${topic}/interaction-handoff.md when UI/UX/design-source interaction is triggered`,
+                    `.zsk/raws/prepare/design/${topic}/design-source-needs.md`,
+                    `.zsk/raws/prepare/design/${topic}/design-source-map.md when provider-backed design sources are used`,
                     ".zsk/evidence/preproposal/{run}/checkpoint-*.md",
                     ".zsk/evidence/preproposal/{run}/readiness-review.md",
                     ...role.outputs,
                 ],
                 evidenceRequired: [
+                    ...(module ? [
+                        `module target is fixed to ${module}; module docs and raw sources are challenged before widening scope`,
+                        `interaction handoff and design-source map use ${module} as the default raw topic unless a narrower page/topic is justified`,
+                    ] : []),
+                    "source-discoverable questions answered before user clarification",
+                    "accepted clarifications, inferred assumptions, and one blocking question are separated",
                     "product checkpoint passes before roadmap/decomposition",
                     "roadmap/decomposition checkpoint passes before UX/design-readiness",
+                    "AI brief drafts and candidate code component mapping exist for source-backed page/module interaction details before asking humans to fill gaps",
+                    "interaction handoff separates sourced provider facts from accepted decisions, assumptions, and missing page/module interaction details when triggered",
                     "UX/design-readiness checkpoint passes before readiness handoff",
                     "final readiness review passes or blocks with owner, missing input, impact, and next action",
                     ...role.evidenceRequired,
                 ],
+                ...(moduleInputs.length > 0 ? { extraInputs: moduleInputs } : {}),
                 contract: {
-                    owns: ["preproposal lane facts, source gaps, checkpoint evidence, and readiness handoff for this role"],
+                    owns: module
+                        ? [`preproposal lane facts, source gaps, checkpoint evidence, and readiness handoff for module ${module}`]
+                        : ["preproposal lane facts, source gaps, checkpoint evidence, and readiness handoff for this role"],
                     doesNotOwn: ["formal module proposal/spec/design/task artifacts", "formal test cases", "implementation edits"],
                     forbiddenDecisions: ["Do not skip checkpoint order.", "Do not treat scenario seeds as formal post-design test cases."],
                     stopCondition: "Preproposal lane output is reviewable, or blockers are recorded for the checkpoint owner.",