@captain_z/zsk 1.8.3 → 1.8.5

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";
+import { type SourceSnapshotAdapterId } from "./source-adapter-normalization.js";
+export type PrepareSyncOptions = {
+    source?: string;
+    all?: boolean;
+    allowNetwork?: boolean;
+    authState?: string;
+    authProfile?: string;
+    browser?: boolean;
+    dryRun?: boolean;
+    runId?: string;
+};
+export type PrepareSyncStatus = "materialized" | "materialized-partial" | "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 = SourceSnapshotAdapterId;
+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 chooseSourceSnapshotStrategy(method: string): string;

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

@@ -0,0 +1,60 @@
+import { resolve } from "node:path";
+import { resolveSourceSnapshot, } from "./config.js";
+import { inferSourceOrigin } from "./origin-detection.js";
+import { selectSourceSnapshotAdapter, } from "./source-adapter-normalization.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 = selectSourceSnapshotAdapter(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 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";
+}
+//# 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":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EACL,qBAAqB,GAItB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,iBAAiB,EAAwB,MAAM,uBAAuB,CAAC;AAChF,OAAO,EACL,2BAA2B,GAE5B,MAAM,mCAAmC,CAAC;AAwE3C,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,MAAc,EACd,MAAqB,EACrB,KAAkB,EAClB,IAAwB,EACxB,uBAA8E;IAE9E,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,qBAAqB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACtD,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/C,MAAM,oBAAoB,GAAG,MAAM,uBAAuB,CAAC,YAAY,CAAC,CAAC;IACzE,MAAM,IAAI,GAAoB;QAC5B,eAAe,EAAE,CAAC;QAClB,SAAS,EAAE,KAAK,CAAC,EAAE;QACnB,UAAU,EAAE,KAAK,CAAC,IAAI;QACtB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM,EAAE,MAAM,CAAC,GAAG;QAClB,QAAQ;QACR,oBAAoB;KACrB,CAAC;IACF,OAAO;QACL,MAAM;QACN,MAAM;QACN,KAAK;QACL,MAAM;QACN,MAAM;QACN,IAAI;QACJ,QAAQ;QACR,YAAY;QACZ,oBAAoB;QACpB,IAAI;KACL,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAA8B,EAC9B,QAAuC;IAEvC,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACzD,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,OAAO;QAAE,OAAO,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAEtE,MAAM,eAAe,GAAG,2BAA2B,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACpF,IAAI,eAAe,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;QACjE,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;IAC5B,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,YAAY;QAAE,OAAO,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAChF,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,KAAK;QAAE,OAAO,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAClE,OAAO,QAAQ,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,MAAc;IACzD,IAAI,MAAM,KAAK,OAAO;QAAE,OAAO,gCAAgC,CAAC;IAChE,IAAI,MAAM,KAAK,YAAY;QAAE,OAAO,0BAA0B,CAAC;IAC/D,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,iCAAiC,CAAC;IAC/D,OAAO,4BAA4B,CAAC;AACtC,CAAC"}

package/dist/core/staffing-plan.d.ts

@@ -188,6 +188,7 @@ type RoleContract = {
 };
 type RolePoolRole = {
     role: string;
+    baseRole?: string;
     subagentType?: string;
     reason?: string;
     stages: string[];

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.",
     },
@@ -378,7 +385,7 @@ async function readStaffingRolePool(target, config) {
     if (config.staffing?.roles) {
         pools.push(parseRolePool({ roles: config.staffing.roles }));
     }
-    return mergeRolePools(...pools);
+    return resolveRoleInheritance(mergeRolePools(...pools));
 }
 function parseRolePool(value) {
     const rolesValue = isRecord(value) ? value.roles : undefined;
@@ -389,16 +396,24 @@ function parseRolePool(value) {
         if (!isRecord(config))
             continue;
         entries.push(rolePoolEntry(role, {
+            baseRole: stringValue(config.extends),
             subagentType: stringValue(config.subagentType),
             reason: stringValue(config.reason),
             stages: stringList(config.stages),
             skills: stringList(config.skills),
-            lanes: stringList(config.lanes),
+            lanes: unique([
+                ...stringList(config.lanes),
+                ...stringList(config.resources),
+                ...stringList(config.artifacts),
+            ]),
             required: booleanValue(config.required),
             remoteSources: booleanValue(config.remoteSources),
             activation: stringValue(config.activation),
             extraInputs: stringList(config.inputs),
-            writeScope: stringList(config.writeScope),
+            writeScope: unique([
+                ...stringList(config.writeScope),
+                ...stringList(config.writeScopes),
+            ]),
             outputs: stringList(config.outputs),
             evidenceRequired: stringList(config.evidenceRequired),
             contract: {
@@ -424,6 +439,7 @@ function mergeRolePools(...pools) {
 function mergeRolePoolRole(base, override) {
     return {
         role: base.role,
+        baseRole: override.baseRole ?? base.baseRole,
         subagentType: override.subagentType ?? base.subagentType,
         reason: override.reason ?? base.reason,
         stages: unique([...base.stages, ...override.stages]),
@@ -442,6 +458,7 @@ function mergeRolePoolRole(base, override) {
 function rolePoolEntry(role, config) {
     return [role, {
             role,
+            baseRole: config.baseRole,
             subagentType: config.subagentType,
             reason: config.reason,
             stages: normalizeList(config.stages ?? []),
@@ -457,6 +474,54 @@ function rolePoolEntry(role, config) {
             contract: config.contract,
         }];
 }
+function resolveRoleInheritance(pool) {
+    const resolving = new Set();
+    const resolved = new Map();
+    const resolveRole = (name) => {
+        const cached = resolved.get(name);
+        if (cached)
+            return cached;
+        const role = pool.roles[name];
+        if (!role)
+            return undefined;
+        if (!role.baseRole) {
+            resolved.set(name, role);
+            return role;
+        }
+        if (resolving.has(name)) {
+            resolved.set(name, role);
+            return role;
+        }
+        resolving.add(name);
+        const base = resolveRole(role.baseRole);
+        resolving.delete(name);
+        const merged = base ? inheritRole(base, role) : role;
+        resolved.set(name, merged);
+        return merged;
+    };
+    for (const name of Object.keys(pool.roles))
+        resolveRole(name);
+    return { roles: Object.fromEntries(resolved) };
+}
+function inheritRole(base, role) {
+    return {
+        role: role.role,
+        baseRole: role.baseRole,
+        subagentType: role.subagentType ?? base.subagentType,
+        reason: role.reason ?? base.reason,
+        stages: unique([...base.stages, ...role.stages]),
+        skills: unique([...base.skills, ...role.skills]),
+        lanes: unique([...base.lanes, ...role.lanes]),
+        required: role.required,
+        remoteSources: base.remoteSources || role.remoteSources,
+        activation: role.activation ?? base.activation,
+        extraInputs: unique([...base.extraInputs, ...role.extraInputs]),
+        writeScope: unique([...base.writeScope, ...role.writeScope]),
+        outputs: unique([...base.outputs, ...role.outputs]),
+        evidenceRequired: unique([...base.evidenceRequired, ...role.evidenceRequired]),
+        contract: mergeContractOverrides(base.contract, role.contract),
+    };
+}
 function seedFromRolePool(role, entries, overrides = {}) {
     return {
         role: role.role,
@@ -464,7 +529,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 +624,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 +725,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 +771,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 +801,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.",