@captain_z/zsk 1.8.3 → 1.8.4

package/dist/core/stage-quality.js

@@ -1,309 +1,12 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { listStageQualityInputStages, normalizeReviewTargetPath, readStageQualityArtifactContents, readStageQualityArtifacts, resolveStageQualityModuleId, reviewModeForReviewTarget, } from "./stage-quality-artifacts.js";
+import { DEFAULT_STAGE_QUALITY_THRESHOLD } from "./stage-quality-contracts.js";
+import { evaluateStageQualityCriteria } from "./stage-quality-criteria.js";
+import { renderGateAssessmentMarkdown, renderWaiverMarkdown, summarizeStageQualityDecision, } from "./stage-quality-rendering.js";
 import { getWorkspacePath } from "./workspace-layout.js";
-const DEFAULT_THRESHOLD = 9;
-const MODULE_STAGES = new Set(["proposal", "spec", "design", "task", "coding", "fix", "smoke", "review", "ready", "verify", "acceptance", "archive"]);
-const SPLITTABLE_MODULE_STAGES = new Set(["proposal", "spec", "design", "tasks"]);
-const SKIPPED_REVIEW_TARGET_DIRS = new Set([
-    ".auth",
-    ".cache",
-    ".git",
-    ".next",
-    ".turbo",
-    "coverage",
-    "dist",
-    "node_modules",
-]);
-const STAGE_INPUTS = {
-    prepare: [
-        { key: "project-config", path: (config) => getWorkspacePath(config, "projectConfig") },
-        { key: "system-spec", path: (config) => getWorkspacePath(config, "systemSpec") },
-    ],
-    preproposal: [],
-    proposal: [
-        { key: "project-config", path: (config) => getWorkspacePath(config, "projectConfig") },
-        { key: "system-spec", path: (config) => getWorkspacePath(config, "systemSpec") },
-        { key: "raw-manifest", path: (config) => getWorkspacePath(config, "rawsManifest") },
-    ],
-    spec: [
-        { key: "project-config", path: (config) => getWorkspacePath(config, "projectConfig") },
-        { key: "system-spec", path: (config) => getWorkspacePath(config, "systemSpec") },
-        { key: "proposal", moduleStage: "proposal" },
-    ],
-    design: [
-        { key: "project-config", path: (config) => getWorkspacePath(config, "projectConfig") },
-        { key: "system-spec", path: (config) => getWorkspacePath(config, "systemSpec") },
-        { key: "spec", moduleStage: "spec" },
-    ],
-    task: [
-        { key: "project-config", path: (config) => getWorkspacePath(config, "projectConfig") },
-        { key: "system-spec", path: (config) => getWorkspacePath(config, "systemSpec") },
-        { key: "proposal", moduleStage: "proposal" },
-        { key: "spec", moduleStage: "spec" },
-        { key: "design", moduleStage: "design" },
-    ],
-    coding: [
-        { key: "tasks", moduleStage: "tasks" },
-    ],
-    fix: [],
-    smoke: [
-        { key: "tasks", moduleStage: "tasks" },
-    ],
-    review: [
-        { key: "spec", moduleStage: "spec" },
-        { key: "design", moduleStage: "design" },
-        { key: "tasks", moduleStage: "tasks" },
-        { key: "smoke", moduleStage: "smoke" },
-    ],
-    ready: [
-        { key: "review", moduleStage: "review" },
-    ],
-    verify: [
-        { key: "ready", moduleStage: "ready" },
-    ],
-    acceptance: [
-        { key: "verify", moduleStage: "verify" },
-    ],
-    archive: [
-        { key: "acceptance", moduleStage: "acceptance" },
-    ],
-};
-const COMMON_CRITERIA = [
-    {
-        id: "GATE-INPUT-01",
-        label: "Required upstream artifacts exist and are non-empty.",
-        weight: 2,
-        required: true,
-        test: (ctx) => ctx.artifacts.every((artifact) => artifact.exists && artifact.bytes > 0),
-        evidence: (ctx) => ctx.artifacts.map((artifact) => `${artifact.key}: ${artifact.exists ? `${artifact.bytes} bytes` : "missing"} (${artifact.path})`),
-        gap: "One or more required upstream artifacts are missing or empty.",
-    },
-    {
-        id: "GATE-RULES-01",
-        label: "PROJECT-CONFIG.md and SYSTEM-SPEC.md constraints are available or explicitly not required for this stage.",
-        weight: 1,
-        required: true,
-        test: (ctx) => {
-            if (["preproposal", "coding", "fix", "smoke", "review", "ready", "verify", "acceptance", "archive"].includes(ctx.stage))
-                return true;
-            return hasContent(ctx, "project-config") && hasContent(ctx, "system-spec");
-        },
-        evidence: (ctx) => ["project-config", "system-spec"].map((key) => `${key}: ${hasContent(ctx, key) ? "present" : "missing"}`),
-        gap: "Project/system rules are not available for a stage that must obey them before handoff.",
-    },
-    {
-        id: "GATE-TEMPLATE-01",
-        label: "Upstream content is not placeholder-only or template filler.",
-        weight: 1,
-        required: true,
-        test: (ctx) => allPrimaryContent(ctx, (content) => {
-            const text = content.toLowerCase();
-            const placeholders = ["<fill-me>", "<project", "<module", "todo:", "tbd", "lorem ipsum"];
-            return !placeholders.some((placeholder) => text.includes(placeholder));
-        }),
-        evidence: (ctx) => primaryArtifacts(ctx).map((artifact) => `${artifact.key}: ${artifact.bytes} bytes`),
-        gap: "At least one upstream artifact still looks like a placeholder or template filler.",
-    },
-    {
-        id: "GATE-CONTENT-01",
-        label: "Upstream content has enough detail for reliable handoff.",
-        weight: 1,
-        test: (ctx) => {
-            const artifacts = primaryArtifacts(ctx);
-            if (artifacts.length === 0)
-                return true;
-            return artifacts.every((artifact) => wordCount(ctx.contentByKey.get(artifact.key) ?? "") >= 40);
-        },
-        evidence: (ctx) => primaryArtifacts(ctx).map((artifact) => `${artifact.key}: ${wordCount(ctx.contentByKey.get(artifact.key) ?? "")} words`),
-        gap: "At least one upstream artifact is very short; treat this as a quality gap unless the project explicitly accepts the risk.",
-    },
-    {
-        id: "GATE-TRACE-01",
-        label: "Claims trace to source, requirement, acceptance, design, task, issue, or evidence identifiers.",
-        weight: 1,
-        test: (ctx) => combinedContent(ctx).match(/\b(FR|NFR|AC|SPEC|DES|TASK|ISSUE|EVIDENCE|ADR|REQ)-?\d+\b/i) !== null ||
-            (ctx.stage === "preproposal" && ctx.artifacts.length === 0) ||
-            /traceability|source|evidence|acceptance|scenario/i.test(combinedContent(ctx)),
-        evidence: (ctx) => [`trace terms found: ${/traceability|source|evidence|acceptance|scenario/i.test(combinedContent(ctx)) ? "yes" : "no"}`],
-        gap: "Traceability is weak; the next stage may rely on chat memory instead of source-backed IDs or evidence.",
-    },
-    {
-        id: "GATE-UNCERTAINTY-01",
-        label: "Open questions, assumptions, risks, or blockers are explicit instead of silently resolved.",
-        weight: 1,
-        test: (ctx) => (ctx.stage === "preproposal" && ctx.artifacts.length === 0) ||
-            /open questions?|assumptions?|risks?|blockers?|constraints?|unknowns?|n\/a|none/i.test(combinedContent(ctx)),
-        evidence: (ctx) => [`uncertainty section marker found: ${/open questions?|assumptions?|risks?|blockers?|constraints?|unknowns?/i.test(combinedContent(ctx)) ? "yes" : "n/a or none marker required"}`],
-        gap: "Uncertainty handling is not explicit enough for a downstream stage to decide whether to continue or ask.",
-    },
-];
-const STAGE_CRITERIA = {
-    design: [
-        {
-            id: "DESIGN-ENTRY-SPEC-01",
-            label: "Spec contains observable acceptance criteria.",
-            weight: 1,
-            required: true,
-            artifactKeys: ["spec"],
-            test: (ctx) => hasPattern(ctx, ["spec"], /acceptance criteria|验收|given\s+.*when\s+.*then|AC-?\d+/is),
-            evidence: () => ["spec acceptance marker required"],
-            gap: "Design cannot safely start until the spec exposes observable acceptance criteria.",
-        },
-        {
-            id: "DESIGN-ENTRY-SPEC-02",
-            label: "Spec covers edge, negative, boundary, or error scenarios.",
-            weight: 1,
-            artifactKeys: ["spec"],
-            test: (ctx) => hasPattern(ctx, ["spec"], /edge cases?|negative|boundary|error|failure|异常|边界/is),
-            evidence: () => ["spec edge/negative/boundary marker required"],
-            gap: "Spec lacks explicit non-happy-path coverage.",
-        },
-        {
-            id: "DESIGN-ENTRY-SPEC-03",
-            label: "Spec names NFR or quality attributes, with missing thresholds marked as 未指定 when needed.",
-            weight: 1,
-            artifactKeys: ["spec"],
-            test: (ctx) => hasPattern(ctx, ["spec"], /NFR|non-functional|performance|security|reliability|accessibility|observability|未指定|质量/is),
-            evidence: () => ["spec NFR/quality marker required"],
-            gap: "Spec does not expose quality attributes enough for design tradeoffs.",
-        },
-        {
-            id: "DESIGN-ENTRY-CONTROL-01",
-            label: "Permission/auth/privacy/data-access behavior has a behavior-level control matrix before design starts.",
-            weight: 2,
-            required: true,
-            artifactKeys: ["spec"],
-            test: (ctx) => !touchesControlConcern(ctx, ["spec"]) || hasControlMatrix(ctx, ["spec"]),
-            evidence: (ctx) => [`control concern: ${touchesControlConcern(ctx, ["spec"]) ? "triggered" : "not triggered"}`],
-            gap: "Spec touches a control concern but lacks a behavior-level control matrix.",
-        },
-    ],
-    task: [
-        {
-            id: "TASK-ENTRY-DES-01",
-            label: "Design includes useful diagrams or explicitly states why diagrams are N/A.",
-            weight: 1,
-            artifactKeys: ["design"],
-            test: (ctx) => hasPattern(ctx, ["design"], /```mermaid|diagram|C4|sequence|state|data flow|flowchart|图|N\/A/is),
-            evidence: () => ["design diagram or N/A rationale marker required"],
-            gap: "Task breakdown needs a reviewable design view or explicit diagram N/A rationale.",
-        },
-        {
-            id: "TASK-ENTRY-DES-02",
-            label: "Design records ADR/decision-record entries for task planning.",
-            weight: 1,
-            required: true,
-            artifactKeys: ["design"],
-            test: (ctx) => hasPattern(ctx, ["design"], /ADR-?\d+|Architecture Decision Record|Decision Record|ADR\s*\/|##\s*ADR|决策记录/is),
-            evidence: () => ["design ADR/decision-record marker required"],
-            gap: "Design lacks ADR/decision-record entries required for task planning.",
-        },
-        {
-            id: "TASK-ENTRY-CONTROL-01",
-            label: "Triggered permission/auth/privacy/data-access behavior has a design control traceability matrix.",
-            weight: 2,
-            required: true,
-            artifactKeys: ["spec", "design"],
-            test: (ctx) => !touchesControlConcern(ctx, ["spec", "design"]) || hasControlMatrix(ctx, ["design"]),
-            evidence: (ctx) => [`control concern: ${touchesControlConcern(ctx, ["spec", "design"]) ? "triggered" : "not triggered"}`],
-            gap: "Spec or design touches a control concern but design lacks a control traceability matrix.",
-        },
-    ],
-    coding: [
-        {
-            id: "CODING-ENTRY-TASK-01",
-            label: "Tasks use Kiro-style nested checkbox groups and subtasks.",
-            weight: 2,
-            required: true,
-            artifactKeys: ["tasks"],
-            test: (ctx) => hasPattern(ctx, ["tasks"], /^- \[ \] \d+\. .+$/m) && hasPattern(ctx, ["tasks"], /^\s+- \[ \] \d+\.\d+ .+$/m),
-            evidence: () => ["task list must contain '- [ ] 1.' and indented '- [ ] 1.1' items"],
-            gap: "Coding should not start from flat or vague tasks; use Kiro-style groups and subtasks.",
-        },
-        {
-            id: "CODING-ENTRY-TASK-02",
-            label: "Each implementation slice has verification or evidence hooks.",
-            weight: 1,
-            required: true,
-            artifactKeys: ["tasks"],
-            test: (ctx) => hasPattern(ctx, ["tasks"], /verification|evidence|test command|pnpm|npm|pytest|vitest|playwright|验证|证据/is),
-            evidence: () => ["task verification/evidence marker required"],
-            gap: "Tasks do not define how each slice proves completion.",
-        },
-    ],
-    fix: [
-        {
-            id: "FIX-ENTRY-ISSUE-01",
-            label: "Issue anchor exposes expected behavior, actual behavior, and evidence.",
-            weight: 2,
-            required: true,
-            artifactKeys: ["issue-record"],
-            test: (ctx) => hasPattern(ctx, ["issue-record"], /expected|actual|evidence|repro|steps|root cause|fix route|预期|实际|证据|复现/is),
-            evidence: () => ["issue record must expose expected/actual/evidence markers"],
-            gap: "Fix should not start without an issue anchor that records expected/actual behavior and evidence.",
-        },
-    ],
-    smoke: [
-        {
-            id: "SMOKE-ENTRY-TEST-01",
-            label: "Test basis is traceable before local smoke claims pass.",
-            weight: 2,
-            required: true,
-            artifactKeys: ["tasks"],
-            test: (ctx) => hasPattern(ctx, ["tasks"], /test basis|acceptance|AC-?\d+|FR-?\d+|scenario|regression|验收|回归/is),
-            evidence: () => ["tasks must link tests to acceptance/scenario/regression basis"],
-            gap: "Smoke cannot treat passing commands as meaningful without a traceable test basis.",
-        },
-    ],
-    review: [
-        {
-            id: "REVIEW-TARGET-01",
-            label: "Explicit review target exists and is treated as the review contract when supplied.",
-            weight: 2,
-            required: true,
-            artifactKeys: ["review-target"],
-            test: (ctx) => !ctx.reviewTarget || hasContent(ctx, "review-target"),
-            evidence: (ctx) => [
-                `review target: ${ctx.reviewTarget ?? "module implementation review"}`,
-                `review mode: ${ctx.reviewMode ?? "implementation"}`,
-            ],
-            gap: "The explicit review target is missing or has no reviewable content.",
-        },
-        {
-            id: "REVIEW-ENTRY-TEST-01",
-            label: "Smoke evidence distinguishes passed, failed, skipped, and unrun checks.",
-            weight: 1,
-            required: true,
-            artifactKeys: ["smoke"],
-            test: (ctx) => ctx.reviewMode !== "implementation" || hasPattern(ctx, ["smoke"], /passed|failed|skipped|unrun|exit status|command|evidence|通过|失败|跳过/is),
-            evidence: (ctx) => [ctx.reviewMode === "implementation" ? "smoke pass/fail/skipped/unrun markers required" : "explicit target review does not require module smoke input"],
-            gap: "Review needs precise test result status, not only a generic all-passed claim.",
-        },
-        {
-            id: "REVIEW-PREPROPOSAL-01",
-            label: "Preproposal/raw-source reviews check product, roadmap, UX, assumptions, or readiness evidence instead of module spec artifacts.",
-            weight: 1,
-            artifactKeys: ["review-target"],
-            test: (ctx) => !["preproposal", "raw-source"].includes(ctx.reviewMode ?? "implementation") ||
-                hasPattern(ctx, ["review-target"], /product|problem|user|persona|journey|roadmap|mvp|phase|ux|flow|assumption|risk|blocker|source|evidence|产品|用户|路线图|阶段|流程|假设|风险|证据/is),
-            evidence: (ctx) => [`target-aware raw review: ${["preproposal", "raw-source"].includes(ctx.reviewMode ?? "implementation") ? "required" : "n/a"}`],
-            gap: "Raw/preproposal review target lacks product, roadmap, UX, assumption, risk, source, or evidence markers.",
-        },
-    ],
-};
-function unknownStageCriterion(stage) {
-    return {
-        id: "GATE-STAGE-00",
-        label: `Stage '${stage}' is known to the gate assessment contract.`,
-        weight: 2,
-        required: true,
-        test: () => false,
-        evidence: () => [`known stages: ${Object.keys(STAGE_INPUTS).join(", ")}`],
-        gap: "Unknown stage; define its required inputs before using gate assessment.",
-    };
-}
+export { normalizeReviewTargetPath, reviewModeForReviewTarget };
 export async function writeGateAssessment(target, config, opts) {
     const bundle = await buildGateAssessment(target, config, opts);
     await mkdir(bundle.artifacts.dir, { recursive: true });
@@ -325,57 +28,28 @@ export function gateThresholdForStage(config, stage) {
 export async function buildGateAssessment(target, config, opts) {
     const stage = safeSlug(opts.stage || "design");
     const threshold = normalizeThreshold(opts.threshold);
-    const moduleId = await resolveModuleId(target, config, stage, opts.module);
-    const reviewTarget = normalizeReviewTarget(target, opts.reviewTarget);
-    const reviewMode = reviewModeFor(reviewTarget);
+    const moduleId = await resolveStageQualityModuleId(target, config, stage, opts.module);
+    const reviewTarget = normalizeReviewTargetPath(target, opts.reviewTarget);
+    const reviewMode = reviewModeForReviewTarget(reviewTarget);
     const runId = createGateRunId();
-    const artifacts = await readGateArtifacts(target, config, stage, moduleId, opts.issue, reviewTarget);
-    const contentByKey = new Map();
-    for (const artifact of artifacts) {
-        if (!artifact.exists)
-            continue;
-        contentByKey.set(artifact.key, await readGateArtifactContent(target, artifact));
-    }
-    const ctx = { stage, ...(reviewTarget ? { reviewTarget, reviewMode } : {}), artifacts, contentByKey };
-    const specs = [
-        ...(!STAGE_INPUTS[stage] ? [unknownStageCriterion(stage)] : []),
-        ...COMMON_CRITERIA,
-        ...(STAGE_CRITERIA[stage] ?? []),
-    ];
-    const criteria = specs.map((spec) => {
-        const passed = spec.test(ctx);
-        return {
-            id: spec.id,
-            label: spec.label,
-            weight: spec.weight,
-            passed,
-            required: spec.required === true,
-            evidence: spec.evidence(ctx),
-            ...(passed ? {} : { gap: spec.gap }),
-        };
+    const artifacts = await readStageQualityArtifacts({
+        target,
+        config,
+        stage,
+        moduleId,
+        issue: opts.issue,
+        reviewTarget,
     });
-    const total = criteria.reduce((sum, criterion) => sum + criterion.weight, 0);
-    const earned = criteria.filter((criterion) => criterion.passed).reduce((sum, criterion) => sum + criterion.weight, 0);
-    const score = total === 0 ? 10 : roundScore((earned / total) * 10);
-    const blockers = criteria
-        .filter((criterion) => criterion.required && !criterion.passed)
-        .map((criterion) => `${criterion.id}: ${criterion.gap ?? criterion.label}`);
-    const gaps = criteria.filter((criterion) => !criterion.passed).map((criterion) => `${criterion.id}: ${criterion.gap ?? criterion.label}`);
-    const belowThreshold = score < threshold;
-    const waiverAllowed = blockers.length === 0 && belowThreshold && Boolean(opts.acceptRisk);
-    const status = blockers.length > 0
-        ? "BLOCKED"
-        : waiverAllowed
-            ? "WAIVED"
-            : belowThreshold
-                ? "NEEDS_CONFIRMATION"
-                : "READY";
-    const decision = status === "READY" || status === "WAIVED"
-        ? "proceed"
-        : status === "NEEDS_CONFIRMATION"
-            ? "human-confirmation-required"
-            : "blocked";
-    const waiver = waiverAllowed ? { reason: opts.acceptRisk, appliedAt: new Date().toISOString() } : undefined;
+    const contentByKey = await readStageQualityArtifactContents(target, artifacts);
+    const criteria = evaluateStageQualityCriteria({
+        stage,
+        reviewTarget,
+        reviewMode,
+        artifacts,
+        contentByKey,
+        knownStages: listStageQualityInputStages(),
+    });
+    const summary = summarizeStageQualityDecision(criteria, threshold, opts.acceptRisk);
     const assessment = {
         version: 1,
         runId,
@@ -383,18 +57,18 @@ export async function buildGateAssessment(target, config, opts) {
         ...(moduleId ? { module: moduleId } : {}),
         ...(reviewTarget ? { reviewTarget, reviewMode } : {}),
         threshold,
-        score,
-        status,
-        decision,
+        score: summary.score,
+        status: summary.status,
+        decision: summary.decision,
         artifacts,
         criteria,
-        blockers,
-        gaps,
-        ...(waiver ? { waiver } : {}),
-        nextAction: nextActionFor(status),
+        blockers: summary.blockers,
+        gaps: summary.gaps,
+        ...(summary.waiver ? { waiver: summary.waiver } : {}),
+        nextAction: summary.nextAction,
     };
     const dir = resolve(target, getWorkspacePath(config, "evidenceRoot"), "gates", runId);
-    const waiverPath = waiver ? join(dir, "risk-acceptance.md") : undefined;
+    const waiverPath = summary.waiver ? join(dir, "risk-acceptance.md") : undefined;
     return {
         assessment,
         artifacts: {
@@ -404,443 +78,17 @@ export async function buildGateAssessment(target, config, opts) {
             ...(waiverPath ? { waiverPath } : {}),
         },
         markdown: renderGateAssessmentMarkdown(assessment),
-        ...(waiver ? { waiverMarkdown: renderWaiverMarkdown(assessment) } : {}),
+        ...(summary.waiver ? { waiverMarkdown: renderWaiverMarkdown(assessment) } : {}),
     };
 }
-async function resolveModuleId(target, config, stage, requested) {
-    if (!MODULE_STAGES.has(stage))
-        return undefined;
-    if (requested)
-        return requested;
-    const modulesRoot = resolve(target, getWorkspacePath(config, "modulesRoot"));
-    try {
-        const entries = (await readdir(modulesRoot, { withFileTypes: true }))
-            .filter((entry) => entry.isDirectory() && !entry.name.startsWith("_"))
-            .map((entry) => entry.name);
-        if (entries.length === 1)
-            return entries[0];
-    }
-    catch {
-        // Missing modules root is handled as missing artifacts by the assessment.
-    }
-    return undefined;
-}
-async function readGateArtifacts(target, config, stage, moduleId, issue, reviewTarget) {
-    if (stage === "fix")
-        return readFixGateArtifacts(target, config, moduleId, issue);
-    if (stage === "review" && reviewTarget)
-        return [await readPathArtifact(target, "review-target", reviewTarget)];
-    const specs = STAGE_INPUTS[stage] ?? [];
-    const artifacts = [];
-    for (const spec of specs) {
-        if (spec.moduleStage) {
-            artifacts.push(await readModuleStageArtifact(target, config, spec.key, spec.moduleStage, moduleId));
-            continue;
-        }
-        const path = spec.path?.(config, moduleId);
-        if (!path) {
-            artifacts.push({ key: spec.key, path: "<module-required>", exists: false, bytes: 0 });
-            continue;
-        }
-        const abs = resolve(target, path);
-        const exists = existsSync(abs);
-        artifacts.push({
-            key: spec.key,
-            path,
-            exists,
-            bytes: exists ? Buffer.byteLength(await readFile(abs, "utf8")) : 0,
-        });
-    }
-    return artifacts;
-}
-async function readPathArtifact(target, key, path) {
-    const boundary = resolve(target);
-    const abs = resolve(boundary, path);
-    if (!isInsidePath(boundary, abs))
-        throw new Error(`review target must stay under project root: ${path}`);
-    try {
-        const info = await stat(abs);
-        if (info.isFile()) {
-            return { key, path, exists: true, bytes: Buffer.byteLength(await readFile(abs, "utf8")) };
-        }
-        if (info.isDirectory()) {
-            const content = await readReviewTargetDirectoryContent(abs);
-            return { key, path, exists: true, bytes: Buffer.byteLength(content) };
-        }
-    }
-    catch {
-        // Missing paths are reported as missing artifacts by the assessment.
-    }
-    return { key, path, exists: false, bytes: 0 };
-}
-async function readModuleStageArtifact(target, config, key, stage, moduleId) {
-    const path = moduleStagePath(config, stage, moduleId);
-    if (!path)
-        return { key, path: "<module-required>", exists: false, bytes: 0 };
-    const abs = resolve(target, path);
-    try {
-        const info = await stat(abs);
-        if (info.isFile()) {
-            return { key, path, exists: true, bytes: Buffer.byteLength(await readFile(abs, "utf8")) };
-        }
-    }
-    catch {
-        // Fall through to stage-directory lookup for splittable artifacts.
-    }
-    if (!SPLITTABLE_MODULE_STAGES.has(stage)) {
-        return { key, path, exists: false, bytes: 0 };
-    }
-    const indexPath = moduleStageIndexPath(config, stage, moduleId);
-    if (!indexPath)
-        return { key, path, exists: false, bytes: 0 };
-    const indexAbs = resolve(target, indexPath);
-    try {
-        const info = await stat(indexAbs);
-        if (!info.isFile())
-            return { key, path: indexPath, exists: false, bytes: 0 };
-        const content = await readStageDirectoryContent(indexAbs);
-        return { key, path: indexPath, exists: true, bytes: Buffer.byteLength(content) };
-    }
-    catch {
-        return { key, path, exists: false, bytes: 0 };
-    }
-}
-async function readFixGateArtifacts(target, config, moduleId, issue) {
-    const path = await resolveIssueArtifactPath(target, config, moduleId, issue);
-    if (!path)
-        return [{ key: "issue-record", path: "<issue-required>", exists: false, bytes: 0 }];
-    const abs = resolve(target, path);
-    const exists = existsSync(abs);
-    return [{
-            key: "issue-record",
-            path,
-            exists,
-            bytes: exists ? Buffer.byteLength(await readFile(abs, "utf8")) : 0,
-        }];
-}
-async function resolveIssueArtifactPath(target, config, moduleId, issue) {
-    const value = issue?.trim();
-    if (!value)
-        return undefined;
-    if (looksLikeIssuePath(value))
-        return normalizeIssuePath(target, value);
-    const candidates = await collectIssueRecordCandidates(target, config, moduleId);
-    return candidates.find((candidate) => issueKey(candidate) === value) ??
-        candidates.find((candidate) => issueKey(candidate).startsWith(`${value}-`));
-}
-async function normalizeIssuePath(target, value) {
-    const abs = resolve(target, value);
-    try {
-        const info = await stat(abs);
-        if (info.isDirectory())
-            return toProjectPath(target, join(abs, "issue.md"));
-    }
-    catch {
-        // Missing issue paths are returned as-is so the gate can report the missing artifact.
-    }
-    if (!extname(value))
-        return toProjectPath(target, join(abs, "issue.md"));
-    return toProjectPath(target, abs);
-}
-async function collectIssueRecordCandidates(target, config, moduleId) {
-    const roots = [
-        ...(moduleId ? [resolve(target, getWorkspacePath(config, "moduleIssues", { module: moduleId }))] : []),
-        resolve(target, getWorkspacePath(config, "issuesRoot")),
-        resolve(target, getWorkspacePath(config, "issuesRoot"), "global"),
-        resolve(target, getWorkspacePath(config, "issuesRoot"), "shared"),
-        resolve(target, getWorkspacePath(config, "issuesRoot"), "public"),
-    ];
-    const files = [];
-    for (const root of roots)
-        files.push(...(await collectIssueFiles(root)));
-    return [...new Set(files.map((file) => toProjectPath(target, file)))].sort();
-}
-async function collectIssueFiles(root) {
-    try {
-        const entries = await readdir(root, { withFileTypes: true });
-        const files = [];
-        for (const entry of entries) {
-            const path = join(root, entry.name);
-            if (entry.isDirectory())
-                files.push(...(await collectIssueFiles(path)));
-            if (entry.isFile() && entry.name !== "index.md" && entry.name.endsWith(".md"))
-                files.push(path);
-        }
-        return files;
-    }
-    catch {
-        return [];
-    }
-}
-function looksLikeIssuePath(value) {
-    return value.includes("/") || value.endsWith(".md") || value.startsWith(".");
-}
-function issueKey(path) {
-    const name = basename(path);
-    return name === "issue.md" ? basename(dirname(path)) : name.replace(/\.md$/i, "");
-}
-function toProjectPath(target, path) {
-    return relative(target, path).split("\\").join("/");
-}
-function moduleStagePath(config, stage, moduleId) {
-    if (!moduleId)
-        return undefined;
-    return join(getWorkspacePath(config, "modulesRoot"), moduleId, `${stage}.md`);
-}
-function moduleStageIndexPath(config, stage, moduleId) {
-    if (!moduleId)
-        return undefined;
-    return join(getWorkspacePath(config, "modulesRoot"), moduleId, stage, "index.md");
-}
-async function readGateArtifactContent(target, artifact) {
-    const boundary = resolve(target);
-    const abs = resolve(boundary, artifact.path);
-    if (!isInsidePath(boundary, abs))
-        throw new Error(`gate artifact must stay under project root: ${artifact.path}`);
-    if (basename(abs) === "index.md" && SPLITTABLE_MODULE_STAGES.has(basename(dirname(abs)))) {
-        return readStageDirectoryContent(abs);
-    }
-    try {
-        const info = await stat(abs);
-        if (info.isDirectory())
-            return readReviewTargetDirectoryContent(abs);
-    }
-    catch {
-        // The caller only asks for content after the artifact exists; fall through
-        // to the file read so the original error remains visible if the path races.
-    }
-    return readFile(abs, "utf8");
-}
-async function readReviewTargetDirectoryContent(dir) {
-    const files = await collectReviewableFiles(dir, dir);
-    const contents = [];
-    for (const file of files) {
-        try {
-            contents.push(await readFile(file, "utf8"));
-        }
-        catch {
-            // Ignore unreadable children; the target can still be reviewed from the
-            // accessible files and the missing child remains a review finding.
-        }
-    }
-    return contents.join("\n\n");
-}
-async function collectReviewableFiles(root, boundary) {
-    try {
-        const entries = await readdir(root, { withFileTypes: true });
-        const files = [];
-        for (const entry of entries) {
-            if (shouldSkipReviewTargetEntry(entry.name))
-                continue;
-            const path = join(root, entry.name);
-            if (!isInsidePath(boundary, path))
-                continue;
-            if (entry.isDirectory()) {
-                files.push(...(await collectReviewableFiles(path, boundary)));
-                continue;
-            }
-            if (entry.isFile() && /\.(md|mdx|ya?ml|json|txt)$/i.test(entry.name))
-                files.push(path);
-        }
-        return files.sort();
-    }
-    catch {
-        return [];
-    }
-}
-function normalizeReviewTarget(target, value) {
-    return normalizeReviewTargetPath(target, value);
-}
-export function normalizeReviewTargetPath(target, value) {
-    const trimmed = value?.trim();
-    if (!trimmed)
-        return undefined;
-    const boundary = resolve(target);
-    const abs = resolve(boundary, trimmed);
-    if (isInsidePath(boundary, abs))
-        return toProjectPath(boundary, abs) || ".";
-    throw new Error(`review target must stay under project root: ${trimmed}`);
-}
-function reviewModeFor(reviewTarget) {
-    return reviewModeForReviewTarget(reviewTarget);
-}
-export function reviewModeForReviewTarget(reviewTarget) {
-    if (!reviewTarget)
-        return undefined;
-    const path = reviewTarget.replace(/\\/g, "/");
-    if (path === ".zsk" || path.startsWith(".zsk/")) {
-        if (path.startsWith(".zsk/raws/prepare/product") ||
-            path.startsWith(".zsk/raws/prepare/roadmap") ||
-            path.startsWith(".zsk/raws/prepare/ux") ||
-            path.startsWith(".zsk/raws/prepare/design") ||
-            path.startsWith(".zsk/evidence/preproposal"))
-            return "preproposal";
-        if (path.startsWith(".zsk/raws/design/") || path.startsWith(".zsk/raws/visual/") || path.includes("/design-source"))
-            return "design-source";
-        if (path.startsWith(".zsk/raws/"))
-            return "raw-source";
-        if (/^\.zsk\/modules\/[^/]+\/(?:proposal|spec|design|tasks?)(?:\.md|\/|$)/.test(path))
-            return "stage-doc";
-        return "zsk-workspace";
-    }
-    if (/\.(?:cjs|cts|js|jsx|mjs|mts|ts|tsx|vue|svelte|css|scss|go|rs|java|kt|swift|py|rb|php|cs|cpp|c|h|hpp)$/i.test(path))
-        return "code-target";
-    if (/(?:design|figma|prototype|wireframe|mockup|screen|asset)/i.test(path))
-        return "design-source";
-    return "target-path";
-}
-function shouldSkipReviewTargetEntry(name) {
-    if (SKIPPED_REVIEW_TARGET_DIRS.has(name))
-        return true;
-    return /(?:storage-state|storagestate|cookies?|tokens?|secrets?|credentials?)\.(?:json|ya?ml|txt)$/i.test(name);
-}
-async function readStageDirectoryContent(indexPath) {
-    const indexContent = await readFile(indexPath, "utf8");
-    const dir = dirname(indexPath);
-    const linkedChildren = linkedMarkdownChildren(indexContent, dir);
-    const childContents = [];
-    for (const child of linkedChildren) {
-        try {
-            const info = await stat(child);
-            if (info.isFile())
-                childContents.push(await readFile(child, "utf8"));
-        }
-        catch {
-            // Missing linked children are handled by zsk check; gate content still
-            // relies on the index so the artifact cannot pass from hidden files.
-        }
-    }
-    return [indexContent, ...childContents].join("\n\n");
-}
-function linkedMarkdownChildren(content, dir) {
-    const files = new Set();
-    for (const match of content.matchAll(/\[[^\]]+\]\(([^)]+?\.md)(?:#[^)]+)?\)/gi)) {
-        const raw = match[1]?.trim();
-        if (!raw || /^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith("/"))
-            continue;
-        const resolved = resolve(dir, raw);
-        if (!isInsidePath(dir, resolved) || resolved === resolve(dir, "index.md"))
-            continue;
-        files.add(resolved);
-    }
-    return [...files].sort();
-}
-function isInsidePath(parent, child) {
-    const rel = relative(parent, child);
-    return rel === "" || (!rel.startsWith("..") && !rel.startsWith("/") && !rel.includes("..\\"));
-}
-function hasContent(ctx, key) {
-    return (ctx.contentByKey.get(key)?.trim().length ?? 0) > 0;
-}
-function primaryArtifacts(ctx) {
-    return ctx.artifacts.filter((artifact) => !["project-config", "system-spec", "raw-manifest"].includes(artifact.key));
-}
-function allPrimaryContent(ctx, test) {
-    const artifacts = primaryArtifacts(ctx);
-    if (artifacts.length === 0)
-        return ctx.artifacts.every((artifact) => artifact.exists && artifact.bytes > 0);
-    return artifacts.every((artifact) => {
-        const content = ctx.contentByKey.get(artifact.key);
-        return typeof content === "string" && test(content);
-    });
-}
-function combinedContent(ctx) {
-    return [...ctx.contentByKey.values()].join("\n\n");
-}
-function hasPattern(ctx, keys, pattern) {
-    return keys.some((key) => pattern.test(ctx.contentByKey.get(key) ?? ""));
-}
-function touchesControlConcern(ctx, keys) {
-    return hasPattern(ctx, keys, /auth(?:entication|orization)?|permission|access control|role|tenant|privacy|data access|compliance|audit|credential|PII|RBAC|ABAC|权限|认证|授权|角色|租户|隐私|审计|合规|凭证/is);
-}
-function hasControlMatrix(ctx, keys) {
-    return hasPattern(ctx, keys, /control (?:traceability )?matrix|control matrix|permission matrix|access control matrix|权限(?:追踪|控制)?矩阵|Source Rule|Subject \/ Actor|Action \/ Capability|Resource \/ Data|Enforcement Point/is);
-}
-function wordCount(content) {
-    return content.split(/\s+/).filter(Boolean).length;
+export function createGateRunId(now = new Date()) {
+    return `${now.toISOString().replace(/[:.]/g, "-")}-${randomUUID().slice(0, 12)}`;
 }
 function normalizeThreshold(value) {
     if (typeof value !== "number" || Number.isNaN(value))
-        return DEFAULT_THRESHOLD;
+        return DEFAULT_STAGE_QUALITY_THRESHOLD;
     return Math.min(10, Math.max(0, value));
 }
-function roundScore(value) {
-    return Math.round(value * 10) / 10;
-}
-function nextActionFor(status) {
-    if (status === "READY")
-        return "Proceed to the requested stage with the recorded assessment evidence.";
-    if (status === "WAIVED")
-        return "Proceed with the accepted risk and carry the gaps into the next stage output.";
-    if (status === "NEEDS_CONFIRMATION")
-        return "Ask for human confirmation, improve upstream artifacts, or rerun with --accept-risk and a concrete reason.";
-    return "Do not start the stage; fix missing required artifacts or required criteria first.";
-}
-function renderGateAssessmentMarkdown(assessment) {
-    return [
-        "# Stage Gate Assessment",
-        "",
-        `- Stage: \`${assessment.stage}\``,
-        ...(assessment.module ? [`- Module: \`${assessment.module}\``] : []),
-        ...(assessment.reviewTarget ? [`- Review target: \`${assessment.reviewTarget}\``] : []),
-        ...(assessment.reviewMode ? [`- Review mode: \`${assessment.reviewMode}\``] : []),
-        `- Score: ${assessment.score}/10`,
-        `- Threshold: ${assessment.threshold}/10`,
-        `- Status: \`${assessment.status}\``,
-        `- Decision: \`${assessment.decision}\``,
-        `- Next action: ${assessment.nextAction}`,
-        "",
-        "## Artifacts",
-        "",
-        "| Key | Path | Status | Bytes |",
-        "| --- | --- | --- | --- |",
-        ...assessment.artifacts.map((artifact) => `| ${artifact.key} | \`${artifact.path}\` | ${artifact.exists ? "present" : "missing"} | ${artifact.bytes} |`),
-        "",
-        "## Criteria",
-        "",
-        "| ID | Result | Required | Weight | Gap | Evidence |",
-        "| --- | --- | --- | --- | --- | --- |",
-        ...assessment.criteria.map((criterion) => `| ${criterion.id} | ${criterion.passed ? "PASS" : "FAIL"} | ${criterion.required ? "yes" : "no"} | ${criterion.weight} | ${criterion.gap ?? ""} | ${criterion.evidence.join("<br>")} |`),
-        "",
-        "## Blockers",
-        "",
-        ...(assessment.blockers.length > 0 ? assessment.blockers.map((blocker) => `- ${blocker}`) : ["- none"]),
-        "",
-        "## Gaps",
-        "",
-        ...(assessment.gaps.length > 0 ? assessment.gaps.map((gap) => `- ${gap}`) : ["- none"]),
-        ...(assessment.waiver ? [
-            "",
-            "## Risk Acceptance",
-            "",
-            `- Reason: ${assessment.waiver.reason}`,
-            `- Applied at: ${assessment.waiver.appliedAt}`,
-        ] : []),
-        "",
-    ].join("\n");
-}
-function renderWaiverMarkdown(assessment) {
-    return [
-        "# Risk Acceptance",
-        "",
-        `- Stage: \`${assessment.stage}\``,
-        ...(assessment.module ? [`- Module: \`${assessment.module}\``] : []),
-        `- Score: ${assessment.score}/10`,
-        `- Threshold: ${assessment.threshold}/10`,
-        `- Reason: ${assessment.waiver?.reason ?? ""}`,
-        `- Applied at: ${assessment.waiver?.appliedAt ?? ""}`,
-        "",
-        "## Accepted Gaps",
-        "",
-        ...(assessment.gaps.length > 0 ? assessment.gaps.map((gap) => `- ${gap}`) : ["- none"]),
-        "",
-        "This waiver does not convert missing required artifacts into PASS. It only records an explicit human risk decision for quality gaps that are below the configured threshold.",
-        "",
-    ].join("\n");
-}
-export function createGateRunId(now = new Date()) {
-    return `${now.toISOString().replace(/[:.]/g, "-")}-${randomUUID().slice(0, 12)}`;
-}
 function safeSlug(value) {
     return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }