@captain_z/zsk 1.8.2 → 1.8.4

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.d.ts

@@ -1,11 +1,13 @@
 import { type ProjectConfig } from "./config.js";
-import { type GateAssessment } from "./stage-quality.js";
+import { type GateAssessment, type ReviewGateMode } from "./stage-quality.js";
 export type StaffingPlanOptions = {
     stage?: string;
     skill?: string;
     surface?: string;
     runId?: string;
     module?: string;
+    issue?: string;
+    reviewTarget?: string;
     gateThreshold?: number;
     acceptRisk?: string;
 };
@@ -118,6 +120,8 @@ export type StaffingStageGate = {
     runId: string;
     stage: string;
     module?: string;
+    reviewTarget?: string;
+    reviewMode?: ReviewGateMode;
     status: GateAssessment["status"];
     decision: GateAssessment["decision"];
     score: number;
@@ -133,6 +137,8 @@ export type StaffingPlan = {
     stage: string;
     skill: string;
     module?: string;
+    reviewTarget?: string;
+    reviewMode?: ReviewGateMode;
     surface: string;
     stageGate?: StaffingStageGate;
     orchestration: StaffingOrchestration;

package/dist/core/staffing-plan.js

@@ -3,7 +3,7 @@ import { dirname, join, resolve } from "node:path";
 import YAML from "yaml";
 import { flattenProjectSources } from "./config.js";
 import { inferSourceOrigin } from "./origin-detection.js";
-import { gateThresholdForStage, writeGateAssessment } from "./stage-quality.js";
+import { gateThresholdForStage, normalizeReviewTargetPath, reviewModeForReviewTarget, writeGateAssessment, } from "./stage-quality.js";
 import { getWorkspacePath } from "./workspace-layout.js";
 const DEFAULT_PACKET_TIMEOUT_POLICY = {
     heartbeatIntervalMs: 60_000,
@@ -11,6 +11,20 @@ const DEFAULT_PACKET_TIMEOUT_POLICY = {
     maxAttempts: 2,
     onTimeout: "fallback-to-leader-sequential",
 };
+const PREPROPOSAL_ROLE_NAMES = [
+    "product-owner",
+    "business-analyst",
+    "planner",
+    "ux-specialist",
+    "design-specialist",
+    "frontend-engineer",
+    "architect",
+    "qa-engineer",
+    "researcher",
+    "verifier",
+    "lead-integrator",
+];
+const PREPROPOSAL_REVIEW_MODES = new Set(["preproposal", "raw-source"]);
 const BUILTIN_ROLE_POOL = {
     roles: Object.fromEntries([
         rolePoolEntry("lead-integrator", {
@@ -29,21 +43,21 @@ const BUILTIN_ROLE_POOL = {
         }),
         rolePoolEntry("product-owner", {
             subagentType: "analyst",
-            stages: ["prepare", "proposal", "spec", "review", "verify", "acceptance"],
+            stages: ["prepare", "preproposal", "proposal", "spec", "review", "verify", "acceptance"],
             lanes: ["product", "pm", "requirement", "requirements", "srs", "prd"],
             activation: "when product or requirement evidence is configured or in scope",
             reason: "interpret product scope, requirement semantics, priorities, and acceptance gaps",
         }),
         rolePoolEntry("business-analyst", {
             subagentType: "analyst",
-            stages: ["proposal", "spec"],
+            stages: ["preproposal", "proposal", "spec"],
             lanes: ["business", "domain", "process", "rules"],
             activation: "when domain process or business-rule evidence is configured or in scope",
             reason: "map domain process, terminology, business rules, and edge cases",
         }),
         rolePoolEntry("architect", {
             subagentType: "architect",
-            stages: ["proposal", "spec", "design", "review"],
+            stages: ["preproposal", "proposal", "spec", "design", "review"],
             activation: "when architecture, API, system-boundary, or dependency decisions are in scope",
             reason: "review system boundaries, module relationships, contracts, and technical risks",
         }),
@@ -56,28 +70,28 @@ 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", "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",
         }),
         rolePoolEntry("ux-specialist", {
             subagentType: "designer",
-            stages: ["prepare"],
+            stages: ["prepare", "preproposal"],
             lanes: ["ux", "ue", "user-experience", "research"],
             activation: "when UX, UE, user-flow, or research sources are configured",
             reason: "inspect user flows, interaction constraints, and usability ambiguity",
         }),
         rolePoolEntry("qa-engineer", {
             subagentType: "test-engineer",
-            stages: ["prepare", "spec", "task", "coding", "review", "verify"],
+            stages: ["prepare", "preproposal", "spec", "task", "coding", "fix", "review", "verify"],
             lanes: ["qa", "test", "testing", "quality"],
             activation: "when QA, test, acceptance, or quality evidence is configured or in scope",
             reason: "connect requirements to acceptance scenarios, test coverage, and verification evidence",
@@ -104,19 +118,19 @@ const BUILTIN_ROLE_POOL = {
         }),
         rolePoolEntry("researcher", {
             subagentType: "researcher",
-            stages: ["prepare"],
+            stages: ["prepare", "preproposal"],
             activation: "optional when current official or external evidence is required",
             reason: "collect official/current external references only when configured local sources are insufficient",
         }),
         rolePoolEntry("planner", {
             subagentType: "planner",
-            stages: ["task"],
+            stages: ["preproposal", "task"],
             activation: "when task sequencing, dependencies, and risk flags are in scope",
             reason: "sequence implementation tasks, dependencies, ownership, and evidence hooks",
         }),
         rolePoolEntry("executor", {
             subagentType: "executor",
-            stages: ["task", "coding"],
+            stages: ["task", "coding", "fix"],
             activation: "when implementation ownership, write scope, or scoped code changes are in scope",
             reason: "implement or estimate scoped code ownership and write boundaries",
         }),
@@ -159,9 +173,13 @@ const ROLE_CONTRACTS = {
         outputs: [
             ".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: [
@@ -173,15 +191,23 @@ const ROLE_CONTRACTS = {
     "product-owner": {
         owns: ["business goals, product scope, priorities, requirement semantics, and acceptance meaning"],
         doesNotOwn: ["backend implementation details", "technical feasibility signoff without architect/engineer evidence"],
-        outputs: [".zsk/evidence/{scope}/{run}/product-source-report.md"],
-        evidenceRequired: ["requirement/source IDs or paths behind each product claim", "open requirement gaps and acceptance risks"],
+        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", "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.",
     },
     "business-analyst": {
         owns: ["domain process, terminology, business rules, and edge cases"],
         doesNotOwn: ["UI aesthetics", "implementation architecture"],
-        outputs: [".zsk/evidence/{scope}/{run}/business-rule-map.md"],
+        outputs: [
+            ".zsk/evidence/{scope}/{run}/business-rule-map.md",
+            ".zsk/raws/prepare/product/{topic}/business-context.md when running preproposal",
+        ],
         evidenceRequired: ["business rule source references", "ambiguity list for unresolved process or terminology conflicts"],
         forbiddenDecisions: ["Do not choose product priority or implementation strategy.", "Do not resolve contradictory business rules silently."],
         stopCondition: "Rules, edge cases, and unresolved ambiguities are documented for lead-integrator.",
@@ -189,7 +215,11 @@ const ROLE_CONTRACTS = {
     architect: {
         owns: ["system boundaries, module relationships, data flow, integration risks, and API/dependency boundaries"],
         doesNotOwn: ["product priority decisions", "business acceptance signoff"],
-        outputs: [".zsk/evidence/{scope}/{run}/architecture-review.md"],
+        outputs: [
+            ".zsk/evidence/{scope}/{run}/architecture-review.md",
+            ".zsk/raws/prepare/product/{topic}/roadmap.md when running preproposal",
+            ".zsk/evidence/preproposal/{run}/checkpoint-roadmap-review.md when running preproposal",
+        ],
         evidenceRequired: ["referenced files, modules, APIs, or diagrams behind architecture claims", "risk map with owner and verification hook"],
         forbiddenDecisions: ["Do not override product acceptance or source truth.", "Do not widen implementation scope without lead-integrator handoff."],
         stopCondition: "Architecture risks and boundary decisions are ready for integration or recorded as blockers.",
@@ -203,26 +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"],
-        evidenceRequired: ["design/prototype source references", "screen/state map and missing asset list"],
+        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, 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"],
-        evidenceRequired: ["flow/source references", "usability risks and unresolved interaction questions"],
+        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", "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.",
     },
@@ -237,8 +277,11 @@ const ROLE_CONTRACTS = {
     "qa-engineer": {
         owns: ["test cases, regression matrix, acceptance scenarios, Playwright/runtime evidence, and test gaps"],
         doesNotOwn: ["business signoff", "implementation design ownership"],
-        outputs: [".zsk/evidence/{scope}/{run}/qa-evidence-report.md"],
-        evidenceRequired: ["test command/scenario evidence", "acceptance coverage and missing-test gaps"],
+        outputs: [
+            ".zsk/evidence/{scope}/{run}/qa-evidence-report.md",
+            ".zsk/raws/prepare/product/{topic}/scenario-seeds.md when running preproposal",
+        ],
+        evidenceRequired: ["test command/scenario evidence", "acceptance coverage and missing-test gaps", "scenario seeds and formal-test-case deferral when running preproposal"],
         forbiddenDecisions: ["Do not treat unrun tests as passing.", "Do not accept partial snapshots as complete evidence."],
         stopCondition: "Coverage status is pass/fail/blocked with concrete evidence and residual risk.",
     },
@@ -428,11 +471,11 @@ 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 ?? [])]),
-        contract: role.contract,
+        contract: mergeContractOverrides(role.contract, overrides.contract),
     };
 }
 function roleMatchesStageOrSkill(role, stage, skill) {
@@ -461,6 +504,8 @@ function summarizeStageGate(assessment, assessmentPath, markdownPath, waiverPath
         runId: assessment.runId,
         stage: assessment.stage,
         ...(assessment.module ? { module: assessment.module } : {}),
+        ...(assessment.reviewTarget ? { reviewTarget: assessment.reviewTarget } : {}),
+        ...(assessment.reviewMode ? { reviewMode: assessment.reviewMode } : {}),
         status: assessment.status,
         decision: assessment.decision,
         score: assessment.score,
@@ -490,6 +535,8 @@ export async function writeStaffingPlan(target, config, opts = {}) {
     const gateBundle = await writeGateAssessment(target, config, {
         stage: bundle.plan.stage,
         module: opts.module,
+        issue: opts.issue,
+        reviewTarget: bundle.plan.reviewTarget,
         threshold: opts.gateThreshold ?? gateThresholdForStage(config, bundle.plan.stage),
         acceptRisk: opts.acceptRisk,
     });
@@ -515,9 +562,11 @@ export function buildStaffingPlan(target, config, opts = {}, rolePool = BUILTIN_
     const stage = normalizeStage(opts.stage ?? "prepare");
     const skill = opts.skill ?? stage;
     const surface = opts.surface ?? "auto";
+    const reviewTarget = stage === "review" ? normalizeReviewTargetPath(target, opts.reviewTarget) : undefined;
+    const reviewMode = reviewModeForReviewTarget(reviewTarget);
     const timeoutPolicy = packetTimeoutPolicyFromConfig(config);
     const entries = flattenProjectSources(config.sources);
-    const seeds = seedRoles(stage, skill, entries, rolePool);
+    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);
@@ -542,6 +591,8 @@ export function buildStaffingPlan(target, config, opts = {}, rolePool = BUILTIN_
         stage,
         skill,
         ...(opts.module ? { module: opts.module } : {}),
+        ...(reviewTarget ? { reviewTarget } : {}),
+        ...(reviewMode ? { reviewMode } : {}),
         surface,
         orchestration,
         uncertaintyPolicy: [
@@ -616,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) {
+function seedRoles(stage, skill, entries, rolePool, reviewMode, module) {
     const seeds = new Map();
     const poolRoles = Object.values(rolePool.roles);
     for (const role of poolRoles) {
@@ -661,6 +712,109 @@ function seedRoles(stage, skill, entries, rolePool) {
             }
         }
     }
+    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: 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/**",
+                    ".zsk/raws/prepare/design/**",
+                    ".zsk/evidence/preproposal/**",
+                    ".zsk/raws/manifest.json",
+                    ".zsk/raws/index.md",
+                    ...role.writeScope,
+                ],
+                outputs: [
+                    `.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: 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.",
+                },
+            }));
+        }
+    }
+    if (stage === "review" && reviewMode && PREPROPOSAL_REVIEW_MODES.has(reviewMode)) {
+        for (const roleName of PREPROPOSAL_ROLE_NAMES) {
+            const role = rolePool.roles[roleName];
+            if (!role)
+                continue;
+            addSeed(seeds, seedFromRolePool(role, [], {
+                activation: `required for ${reviewMode} review target checkpoint coverage`,
+                reason: role.reason || `review ${reviewMode} target for product, roadmap, UX, source, and readiness gaps before formal proposal`,
+                writeScope: [
+                    ".zsk/evidence/review/**",
+                    ".zsk/issues/**",
+                    ...role.writeScope,
+                ],
+                outputs: [
+                    ".zsk/evidence/review/{run}/target-review.md",
+                    ".zsk/evidence/review/{run}/checkpoint-findings.md",
+                    ...role.outputs,
+                ],
+                evidenceRequired: [
+                    "explicit review-target path and review mode",
+                    "product, roadmap/decomposition, UX/design-readiness, assumption, risk, source, and blocker checks where relevant",
+                    "findings grouped by role with pass/blocker/waived result and owner",
+                    "confirmation that missing module spec/design/tasks/smoke are not blockers for raw/preproposal target review",
+                    ...role.evidenceRequired,
+                ],
+                contract: {
+                    owns: ["role-specific findings for the explicit raw/preproposal review target"],
+                    doesNotOwn: ["rewriting raw resources during review", "formal module proposal/spec/design/task production", "implementation edits"],
+                    forbiddenDecisions: ["Do not require module spec/design/tasks/smoke for raw/preproposal target review.", "Do not silently pass missing product/UX/readiness evidence."],
+                    stopCondition: "Target findings are reviewable, or blockers identify owner, missing input, impact, and next action.",
+                },
+            }));
+        }
+    }
     return [...seeds.values()];
 }
 function addSeed(seeds, seed) {
@@ -697,6 +851,7 @@ function buildOrchestrationPlan(surface, stage, entries, seeds, config) {
     const remoteCount = entries.filter((entry) => inferSourceOrigin(entry.source).remote).length;
     const activeSeedCount = seeds.filter((seed) => seedIsActive(seed, stage)).length;
     const stageParallelNeed = (policy.strictReview && ["review", "verify"].includes(stage)) ||
+        (stage === "preproposal" && activeSeedCount > 2) ||
         (["prepare", "design"].includes(stage) && activeSeedCount > 2);
     const hasIndependentLanes = lanes.size > 1 ||
         remoteCount > 0 ||
@@ -1022,6 +1177,8 @@ function renderStaffingPlanMarkdown(plan, timeoutPolicy) {
         `- Stage: \`${plan.stage}\``,
         `- Skill: \`${plan.skill}\``,
         ...(plan.module ? [`- Module: \`${plan.module}\``] : []),
+        ...(plan.reviewTarget ? [`- Review target: \`${plan.reviewTarget}\``] : []),
+        ...(plan.reviewMode ? [`- Review mode: \`${plan.reviewMode}\``] : []),
         `- Surface: \`${plan.surface}\``,
         `- Roles: ${plan.roles.length}`,
         `- Active emit lanes: ${plan.emitPackets.length}`,