@wowok/agent-mcp 2.5.1 → 2.5.3

package/dist/project/deployment-doc.js

@@ -1,3 +1,4 @@
+import { join } from "path";
 const STANDARD_TOPO_ORDER = [
     "permission", "treasury", "allocation", "guard", "machine",
     "service", "order", "progress", "arb", "reward",
@@ -300,6 +301,43 @@ export function generateDeploymentDoc(input) {
     ];
     return sections.filter((s) => s.length > 0).join("\n");
 }
+export function estimateDeploymentGas(input) {
+    const GAS_RATES = {
+        permission: { create: 20_000_000, publish: 0 },
+        progress: { create: 40_000_000, publish: 0 },
+        guard: { create: 30_000_000, publish: 0 },
+        allocation: { create: 40_000_000, publish: 0 },
+        machine: { create: 50_000_000, publish: 200_000_000 },
+        service: { create: 50_000_000, publish: 100_000_000 },
+        arb: { create: 40_000_000, publish: 0 },
+        treasury: { create: 30_000_000, publish: 0 },
+        demand: { create: 40_000_000, publish: 0 },
+        repository: { create: 40_000_000, publish: 0 },
+        reward: { create: 30_000_000, publish: 0 },
+    };
+    const perObject = [];
+    let totalGas = 0;
+    let publishGas = 0;
+    for (const obj of input.objects) {
+        const rate = GAS_RATES[obj.object_type] ?? { create: 40_000_000, publish: 0 };
+        const createGas = obj.reused_from ? 0 : rate.create;
+        const pubGas = obj.publish_required ? rate.publish : 0;
+        const objTotal = createGas + pubGas;
+        perObject.push({
+            entry_id: obj.entry_id,
+            object_type: obj.object_type,
+            create_gas_mist: createGas,
+            publish_gas_mist: pubGas,
+        });
+        totalGas += objTotal;
+        publishGas += pubGas;
+    }
+    return {
+        total_gas_mist: totalGas,
+        per_object: perObject,
+        publish_gas_mist: publishGas,
+    };
+}
 export function validateDeploymentDoc(input) {
     const errors = [];
     const checks = [];
@@ -430,3 +468,597 @@ function runDCheck(item, input) {
 export function getStandardTopoOrder() {
     return [...STANDARD_TOPO_ORDER];
 }
+import { saveProjectFile, saveProjectMarkdown, ensureProjectDir, deploymentDir, } from "./project-store.js";
+const STAGE_D_CHECKS = {
+    1: ["D-01", "D-02", "D-03", "D-04"],
+    2: ["D-05", "D-06", "D-07"],
+    3: ["D-18"],
+    4: ["D-08", "D-09", "D-11", "D-12"],
+    5: ["D-10"],
+};
+const CROSS_STAGE_D_CHECKS = ["D-13", "D-14", "D-15", "D-16", "D-17"];
+const STAGE_GOALS = {
+    1: {
+        stage: 1,
+        goal_statement: "Establish a valid and unique project namespace",
+        derived_from: ["unique_identity", "traceable_versioning"],
+        success_criteria: [
+            { criterion_id: "namespace_prefix_nonempty", description: "Project prefix is non-empty and follows naming regex", measurable: true, target_value: "^[a-z][a-z0-9_]{2,63}$" },
+            { criterion_id: "version_format_valid", description: "Version follows v<n> format", measurable: true, target_value: "^v\\d+$" },
+            { criterion_id: "entry_id_unique", description: "All entry_ids are unique within the project", measurable: true },
+        ],
+    },
+    2: {
+        stage: 2,
+        goal_statement: "Build a complete and cycle-free object dependency graph",
+        derived_from: ["dag_no_cycle", "complete_dependency"],
+        success_criteria: [
+            { criterion_id: "odg_nodes_complete", description: "All required objects are defined", measurable: true },
+            { criterion_id: "odg_edges_legal", description: "All edges reference defined nodes", measurable: true },
+            { criterion_id: "odg_no_cycle", description: "Dependency graph has no cycles", measurable: true },
+            { criterion_id: "scenario_coverage", description: "Declared scenarios are covered by steps", measurable: true },
+        ],
+    },
+    3: {
+        stage: 3,
+        goal_statement: "Calibrate risks and confirm all CRITICAL risks resolved",
+        derived_from: ["risk_acknowledged"],
+        success_criteria: [
+            { criterion_id: "no_critical_risk", description: "No CRITICAL risks remain (risk_status != RISK_BLOCKED)", measurable: true, target_value: "0" },
+            { criterion_id: "high_risk_confirmed", description: "All HIGH risks are user-confirmed", measurable: true },
+        ],
+    },
+    4: {
+        stage: 4,
+        goal_statement: "Generate a complete deployment document with valid steps",
+        derived_from: ["deployable_to_mainnet"],
+        success_criteria: [
+            { criterion_id: "steps_sequential", description: "Step IDs are sequential and unique", measurable: true },
+            { criterion_id: "deps_consistent", description: "Step dependencies are consistent with ODG", measurable: true },
+            { criterion_id: "testnet_mainnet_symmetric", description: "testnet and mainnet phases are symmetric", measurable: true },
+            { criterion_id: "no_d_error", description: "No D-FAIL errors", measurable: true, target_value: "0" },
+        ],
+    },
+    5: {
+        stage: 5,
+        goal_statement: "Trace substeps coherently across the deployment",
+        derived_from: ["deployment_complete"],
+        success_criteria: [
+            { criterion_id: "substeps_coherent", description: "No dangling inputs, circular refs, missing outputs, cross-step breaks", measurable: true },
+            { criterion_id: "no_failed_substep", description: "No substep is in FAILED state", measurable: true },
+        ],
+    },
+};
+const STAGE_RISK_POLICIES = {
+    1: {
+        stage: 1,
+        risks: [
+            { risk_id: "R1-01", category: "naming", description: "Namespace prefix conflicts with existing project", likelihood: "medium", impact: "medium", mitigation: "Check existing projects before committing namespace", owner: "user" },
+            { risk_id: "R1-02", category: "naming", description: "Version format inconsistent", likelihood: "low", impact: "low", mitigation: "Validate version regex", owner: "ai" },
+        ],
+        active_controls: [
+            { control_id: "C1-01", control_type: "preventive", target_risk: "R1-01", implementation: "stage gate checks prefix uniqueness", verified: true },
+            { control_id: "C1-02", control_type: "preventive", target_risk: "R1-02", implementation: "schema validation enforces ^v\\d+$", verified: true },
+        ],
+        residual_risks: [],
+    },
+    2: {
+        stage: 2,
+        risks: [
+            { risk_id: "R2-01", category: "dependency", description: "Missing dependencies (dangling refs)", likelihood: "medium", impact: "high", mitigation: "D-02 check in stage gate", owner: "ai" },
+            { risk_id: "R2-02", category: "dependency", description: "Circular dependencies in ODG", likelihood: "low", impact: "critical", mitigation: "Topological sort detects cycles", owner: "ai" },
+            { risk_id: "R2-03", category: "operational", description: "Cross-project reference (project isolation violation §3.0)", likelihood: "low", impact: "critical", mitigation: "cross_project_reference_check in stage gate", owner: "ai" },
+        ],
+        active_controls: [
+            { control_id: "C2-01", control_type: "detective", target_risk: "R2-01", implementation: "D-02 dangling check", verified: true },
+            { control_id: "C2-02", control_type: "detective", target_risk: "R2-02", implementation: "cycle detection", verified: true },
+            { control_id: "C2-03", control_type: "preventive", target_risk: "R2-03", implementation: "cross-prefix reference scan", verified: true },
+        ],
+        residual_risks: [],
+    },
+    3: {
+        stage: 3,
+        risks: [
+            { risk_id: "R3-01", category: "operational", description: "Unresolved CRITICAL risks", likelihood: "medium", impact: "critical", mitigation: "Block at stage gate until resolved", owner: "user" },
+            { risk_id: "R3-02", category: "operational", description: "Risk confirmation expired (stale)", likelihood: "low", impact: "medium", mitigation: "Re-confirm before deployment", owner: "user" },
+        ],
+        active_controls: [
+            { control_id: "C3-01", control_type: "preventive", target_risk: "R3-01", implementation: "D-16 blocks when risk_status=RISK_BLOCKED", verified: true },
+        ],
+        residual_risks: [],
+    },
+    4: {
+        stage: 4,
+        risks: [
+            { risk_id: "R4-01", category: "operational", description: "Step numbering gaps", likelihood: "low", impact: "medium", mitigation: "D-08 sequential check", owner: "ai" },
+            { risk_id: "R4-02", category: "financial", description: "Mainnet gas budget exceeded", likelihood: "medium", impact: "high", mitigation: "gas_budget_check in stage gate", owner: "user" },
+            { risk_id: "R4-03", category: "operational", description: "Irreversible operation requested", likelihood: "low", impact: "critical", mitigation: "Object lifecycle matrix check (§3.2)", owner: "user" },
+        ],
+        active_controls: [
+            { control_id: "C4-01", control_type: "detective", target_risk: "R4-01", implementation: "D-08 check", verified: true },
+            { control_id: "C4-02", control_type: "detective", target_risk: "R4-02", implementation: "gas estimation", verified: true },
+        ],
+        residual_risks: ["Gas costs are estimates; actual mainnet gas may differ"],
+    },
+    5: {
+        stage: 5,
+        risks: [
+            { risk_id: "R5-01", category: "operational", description: "Substep linkage breaks (dangling/circular/missing)", likelihood: "medium", impact: "high", mitigation: "D-10 substep trace", owner: "ai" },
+            { risk_id: "R5-02", category: "operational", description: "Observe records missing", likelihood: "low", impact: "medium", mitigation: "Append-only audit.jsonl", owner: "ai" },
+            { risk_id: "R5-03", category: "operational", description: "State drift between substeps and stage state", likelihood: "low", impact: "high", mitigation: "Cross-stage check with stage 4", owner: "ai" },
+        ],
+        active_controls: [
+            { control_id: "C5-01", control_type: "detective", target_risk: "R5-01", implementation: "substep-trace.ts coherent check", verified: true },
+        ],
+        residual_risks: [],
+    },
+};
+const PROJECT_INVARIANTS = [
+    { invariant_id: "unique_identity", description: "Project has a unique prefix and version", verified_by_stages: [1] },
+    { invariant_id: "traceable_versioning", description: "All objects trace to a specific project version", verified_by_stages: [1] },
+    { invariant_id: "dag_no_cycle", description: "Object dependency graph has no cycles", verified_by_stages: [2] },
+    { invariant_id: "complete_dependency", description: "All dependencies are resolved", verified_by_stages: [2] },
+    { invariant_id: "project_isolation", description: "No cross-project object references (§3.0)", verified_by_stages: [2] },
+    { invariant_id: "risk_acknowledged", description: "All CRITICAL risks are resolved", verified_by_stages: [3] },
+    { invariant_id: "deployable_to_mainnet", description: "Deployment doc is complete and error-free", verified_by_stages: [4] },
+    { invariant_id: "deployment_complete", description: "Substeps are coherent and traceable", verified_by_stages: [5] },
+];
+function runStageDChecks(stage, input) {
+    const checks = STAGE_D_CHECKS[stage];
+    const fullResult = validateDeploymentDoc(input);
+    const out = [];
+    for (const checkId of checks) {
+        const found = fullResult.checks.find((c) => c.check_id === checkId);
+        if (found) {
+            out.push({
+                check_id: found.check_id,
+                status: found.status.toLowerCase(),
+                message: found.notes ?? "",
+                evidence: found.description,
+            });
+        }
+    }
+    return out;
+}
+function renderStageNamespaceContent(input) {
+    const lines = [];
+    lines.push(`# Stage 1: Namespace — ${input.project_prefix}_${input.version}`, "");
+    lines.push("## Namespace Configuration", "");
+    lines.push(`- **Prefix**: \`${input.project_prefix}\``);
+    lines.push(`- **Version**: \`${input.version}\``);
+    lines.push(`- **Namespace tag**: \`project:${input.project_prefix}_${input.version}\``);
+    lines.push(`- **Business intent**: ${input.business_intent}`);
+    lines.push(`- **Industry**: ${input.industry}`);
+    if (input.author)
+        lines.push(`- **Author**: ${input.author}`);
+    lines.push("");
+    lines.push("## Object Naming", "");
+    lines.push("| entry_id | object_type | name |");
+    lines.push("|----------|-------------|------|");
+    for (const o of input.objects) {
+        lines.push(`| ${o.entry_id} | ${o.object_type} | ${o.name} |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderStagePuzzleContent(input) {
+    const lines = [];
+    lines.push(`# Stage 2: Business Puzzle — ${input.project_prefix}_${input.version}`, "");
+    lines.push("## Object Dependency Graph (ODG)", "");
+    lines.push("### Nodes", "");
+    lines.push("| entry_id | object_type | name | publish_required |");
+    lines.push("|----------|-------------|------|------------------|");
+    for (const o of input.objects) {
+        lines.push(`| ${o.entry_id} | ${o.object_type} | ${o.name} | ${o.publish_required} |`);
+    }
+    lines.push("");
+    lines.push("### Edges", "");
+    lines.push("| from | to | edge_kind | field_path | required_at_publish |");
+    lines.push("|------|----|-----------|-------------|---------------------|");
+    for (const e of input.edges) {
+        lines.push(`| ${e.from} | ${e.to} | ${e.edge_kind} | ${e.field_path} | ${e.required_at_publish} |`);
+    }
+    lines.push("");
+    if (input.scenarios && input.scenarios.length > 0) {
+        lines.push("### Scenarios", "");
+        lines.push("| scenario_id | description | primary_object |");
+        lines.push("|-------------|-------------|----------------|");
+        for (const s of input.scenarios) {
+            lines.push(`| ${s.scenario_id} | ${s.description} | ${s.primary_object} |`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function renderStageRiskContent(input) {
+    const lines = [];
+    lines.push(`# Stage 3: Risk Calibration — ${input.project_prefix}_${input.version}`, "");
+    lines.push("## Risk Status Summary", "");
+    lines.push(`- **risk_status**: ${input.risk_status ?? "(not provided)"}`);
+    lines.push(`- **CRITICAL count**: ${input.risk_critical_count ?? 0}`);
+    lines.push(`- **HIGH count**: ${input.risk_high_count ?? 0}`);
+    lines.push("");
+    lines.push("## D-Check Results (Stage 3 subset: D-18)", "");
+    const checks = runStageDChecks(3, input);
+    lines.push("| check_id | status | message |");
+    lines.push("|----------|--------|---------|");
+    for (const c of checks) {
+        lines.push(`| ${c.check_id} | ${c.status} | ${c.message} |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderStageStepsContent(input) {
+    const lines = [];
+    lines.push(`# Stage 4: Deployment Steps — ${input.project_prefix}_${input.version}`, "");
+    lines.push("## Topological Execution Plan", "");
+    lines.push("| step | object_type | operation | substep_count | depends_on | entry_id | network_phase |");
+    lines.push("|------|-------------|-----------|---------------|------------|----------|---------------|");
+    for (const s of input.steps) {
+        lines.push(`| ${s.step} | ${s.object_type} | ${s.operation} | ${s.substep_count} | [${s.depends_on.join(", ")}] | ${s.entry_id} | ${s.network_phase} |`);
+    }
+    lines.push("");
+    lines.push("## D-Check Results (Stage 4 subset: D-08/D-09/D-11/D-12)", "");
+    const checks = runStageDChecks(4, input);
+    lines.push("| check_id | status | message |");
+    lines.push("|----------|--------|---------|");
+    for (const c of checks) {
+        lines.push(`| ${c.check_id} | ${c.status} | ${c.message} |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderStageSubstepsContent(input) {
+    const lines = [];
+    lines.push(`# Stage 5: Substep Trace — ${input.project_prefix}_${input.version}`, "");
+    lines.push("> Substep records are appended at runtime (substeps-<network>.jsonl).", "");
+    lines.push("> This file records the validation summary.", "");
+    lines.push("");
+    lines.push("## D-Check Results (Stage 5 subset: D-10)", "");
+    lines.push("> D-10 is delegated to substep-trace.ts (C4) — populated at runtime.", "");
+    lines.push("| check_id | status | message |");
+    lines.push("|----------|--------|---------|");
+    lines.push("| D-10 | pending | delegated to substep-trace (C4) |");
+    lines.push("");
+    return lines.join("\n");
+}
+const STAGE_CONTENT_RENDERERS = {
+    1: renderStageNamespaceContent,
+    2: renderStagePuzzleContent,
+    3: renderStageRiskContent,
+    4: renderStageStepsContent,
+    5: renderStageSubstepsContent,
+};
+function generateStageAssessment(stage, input) {
+    const goal = STAGE_GOALS[stage];
+    const goalCompletion = {};
+    const findings = [];
+    const recommendations = [];
+    const dChecks = runStageDChecks(stage, input);
+    const failedChecks = dChecks.filter((c) => c.status === "fail");
+    for (const criterion of goal.success_criteria) {
+        let completion = 1.0;
+        const relatedCheck = dChecks.find((c) => criterion.criterion_id.includes(c.check_id.toLowerCase()));
+        if (relatedCheck) {
+            if (relatedCheck.status === "fail")
+                completion = 0.3;
+            else if (relatedCheck.status === "warn")
+                completion = 0.7;
+        }
+        if (failedChecks.length > 0 && !relatedCheck) {
+            completion = 0.5;
+        }
+        goalCompletion[criterion.criterion_id] = completion;
+        if (completion < 1.0) {
+            findings.push({
+                finding_id: `F-${stage}-${criterion.criterion_id}`,
+                severity: completion < 0.5 ? "critical" : "warn",
+                criterion_id: criterion.criterion_id,
+                description: `Criterion "${criterion.description}" not fully met`,
+                evidence: relatedCheck ? relatedCheck.message : "stage D-checks failed",
+            });
+            recommendations.push(`Address ${criterion.criterion_id}: ${criterion.description}`);
+        }
+    }
+    return {
+        stage,
+        assessed_at: Date.now(),
+        goal_completion: goalCompletion,
+        findings,
+        recommendations,
+    };
+}
+function generateStageVerification(stage, input) {
+    const goal = STAGE_GOALS[stage];
+    const dChecks = runStageDChecks(stage, input);
+    const goalVerification = {};
+    for (const criterion of goal.success_criteria) {
+        const relatedCheck = dChecks.find((c) => criterion.criterion_id.includes(c.check_id.toLowerCase()));
+        const passed = relatedCheck ? relatedCheck.status === "pass" : dChecks.every((c) => c.status !== "fail");
+        goalVerification[criterion.criterion_id] = {
+            passed,
+            evidence: relatedCheck ? relatedCheck.message : "all stage D-checks passed",
+        };
+    }
+    const blockingIssues = [];
+    for (const check of dChecks) {
+        if (check.status === "fail") {
+            blockingIssues.push(`${check.check_id}: ${check.message}`);
+        }
+    }
+    const crossStageChecks = [];
+    if (stage === 2) {
+        crossStageChecks.push({
+            check_id: "CS-2-1",
+            involves_stages: [1, 2],
+            description: "All object names start with the project prefix",
+            passed: input.objects.every((o) => o.name.startsWith(input.project_prefix)),
+            evidence: `prefix=${input.project_prefix}`,
+        });
+    }
+    if (stage === 4) {
+        const entryIds = new Set(input.objects.map((o) => o.entry_id));
+        crossStageChecks.push({
+            check_id: "CS-4-2",
+            involves_stages: [2, 4],
+            description: "All steps reference defined objects",
+            passed: input.steps.every((s) => entryIds.has(s.entry_id)),
+            evidence: `${input.steps.length} steps checked`,
+        });
+    }
+    const stagePassed = blockingIssues.length === 0;
+    return {
+        stage,
+        verified_at: Date.now(),
+        goal_verification: goalVerification,
+        d_checks: dChecks,
+        cross_stage_checks: crossStageChecks,
+        stage_passed: stagePassed,
+        blocking_issues: blockingIssues,
+    };
+}
+function generateValidationChainGraph(input) {
+    const derivations = [];
+    const propagationRules = [];
+    for (const inv of PROJECT_INVARIANTS) {
+        for (const stageNum of inv.verified_by_stages) {
+            const stageGoal = STAGE_GOALS[stageNum];
+            derivations.push({
+                source_type: "project_invariant",
+                source_id: inv.invariant_id,
+                target_type: "stage_goal",
+                target_stage: stageNum,
+                target_id: `goal-stage-${stageNum}`,
+                derivation_logic: `invariant "${inv.invariant_id}" is verified by stage ${stageNum} goal "${stageGoal.goal_statement}"`,
+            });
+            propagationRules.push({
+                rule_id: `PR-${inv.invariant_id}-${stageNum}`,
+                trigger: { stage: stageNum, event: "verification_failed" },
+                effect: { target: "project_invariant", action: "block" },
+            });
+        }
+    }
+    const stageUnits = [1, 2, 3, 4, 5].map((stage) => ({
+        stage,
+        goal_id: `goal-stage-${stage}`,
+        assessment_id: `assessment-stage-${stage}`,
+        risk_policy_id: `risk-policy-stage-${stage}`,
+        verification_id: `verification-stage-${stage}`,
+        artifacts: [
+            `0${stage}-<name>/README.md`,
+            `0${stage}-<name>/assessment.json`,
+            `0${stage}-<name>/risk-policy.json`,
+            `0${stage}-<name>/verification.json`,
+            `0${stage}-<name>/content.md`,
+        ],
+    }));
+    const impactMap = {
+        "puzzle.json": ["02-puzzle/*", "04-steps/*", "README.md"],
+        "risk.json": ["03-risk/*", "04-steps/*", "README.md"],
+        "stage.json": ["README.md"],
+        "substeps-testnet.jsonl": ["05-substeps/*", "README.md"],
+        "substeps-mainnet.jsonl": ["05-substeps/*", "README.md"],
+    };
+    return {
+        version: "1.0.0",
+        generated_at: Date.now(),
+        project_invariants: PROJECT_INVARIANTS,
+        stage_units: stageUnits,
+        derivations,
+        propagation_rules: propagationRules,
+        impact_map: impactMap,
+    };
+}
+function renderProjectReadme(input, relations) {
+    const lines = [];
+    lines.push(`# ${input.project_prefix}_${input.version} — Project Deployment`, "");
+    lines.push("> **Nested-autonomy deployment documentation set**. ", "");
+    lines.push("> Project-level file: goals + invariants + stage index + global ODG + resume entry.", "");
+    lines.push("> Each stage has its own subdirectory with goal/assessment/risk-policy/verification/content.", "");
+    lines.push("");
+    lines.push("## 🔄 Project Resume (entry point for any AI / user)", "");
+    lines.push(`- **Project**: ${input.project_prefix}_${input.version}`);
+    lines.push(`- **Business intent**: ${input.business_intent}`);
+    lines.push(`- **Industry**: ${input.industry}`);
+    lines.push(`- **Generated at**: ${isoNow()}`);
+    lines.push(`- **Schema version**: ${relations.version}`);
+    lines.push("- **Next step**: read stage completion index below, then open the relevant stage subdirectory", "");
+    lines.push("> Project isolation principle (§3.0): each project deploys its OWN objects;", "");
+    lines.push("> cross-project object reuse is forbidden; fork creates a new version that re-creates objects.", "");
+    lines.push("");
+    lines.push("## §1 Project Goals + Invariants", "");
+    lines.push("**Goal**: " + input.business_intent, "");
+    lines.push("### Invariants (derived to stage goals via validation chain)", "");
+    lines.push("| invariant_id | description | verified_by_stages |");
+    lines.push("|--------------|-------------|---------------------|");
+    for (const inv of relations.project_invariants) {
+        lines.push(`| ${inv.invariant_id} | ${inv.description} | [${inv.verified_by_stages.join(", ")}] |`);
+    }
+    lines.push("");
+    lines.push("## §2 Naming Conventions", "");
+    lines.push("- Project prefix regex: `^[a-z][a-z0-9_]{2,63}$`");
+    lines.push("- Version format: `v<n>` (e.g. `v1`, `v2`)");
+    lines.push("- Namespace tag: `project:<prefix>_<version>`");
+    lines.push("- Object naming: `<project>_<type>_<version>`");
+    lines.push("");
+    lines.push("## §3 Standard Topological Order (shared across stages)", "");
+    lines.push("```");
+    lines.push(STANDARD_TOPO_ORDER.join(" → "));
+    lines.push("```", "");
+    lines.push("## §4 D-Check Definitions (18 checks, definitions only — results per stage)", "");
+    lines.push("| check_id | description |");
+    lines.push("|----------|-------------|");
+    for (const item of D_CHECK_ITEMS) {
+        lines.push(`| ${item.id} | ${item.description} |`);
+    }
+    lines.push("");
+    lines.push("## §5 Stage Completion Index", "");
+    lines.push("> Auto-generated; reflects current state of stage subdirectories.", "");
+    lines.push("| Stage | Name | Status | Completion | Last Verified | Passed | Blocking |");
+    lines.push("|-------|------|--------|------------|----------------|--------|----------|");
+    const stageNames = {
+        1: "namespace", 2: "puzzle", 3: "risk", 4: "steps", 5: "substeps",
+    };
+    for (const stage of [1, 2, 3, 4, 5]) {
+        lines.push(`| ${stage} | ${stageNames[stage]} | pending | 0% | - | ⏳ | - |`);
+    }
+    lines.push("> Note: this table is regenerated on each `generate_deployment_doc` call; runtime", "");
+    lines.push("> execution (stage 5 substeps) updates the `05-substeps/` subdirectory append-only.", "");
+    lines.push("");
+    lines.push("## §6 Global Object Dependency Graph (ODG)", "");
+    lines.push("### Nodes", "");
+    lines.push("| entry_id | object_type | name | publish_required | description |");
+    lines.push("|----------|-------------|------|------------------|-------------|");
+    for (const o of input.objects) {
+        lines.push(`| ${o.entry_id} | ${o.object_type} | ${o.name} | ${o.publish_required} | ${o.description ?? ""} |`);
+    }
+    lines.push("");
+    lines.push("### Edges", "");
+    lines.push("| from | to | edge_kind | field_path | required_at_publish |");
+    lines.push("|------|----|-----------|-------------|---------------------|");
+    for (const e of input.edges) {
+        lines.push(`| ${e.from} | ${e.to} | ${e.edge_kind} | ${e.field_path} | ${e.required_at_publish} |`);
+    }
+    lines.push("");
+    const dangling = input.edges.filter((e) => !input.objects.find((o) => o.entry_id === e.from) ||
+        !input.objects.find((o) => o.entry_id === e.to));
+    lines.push("### Dependency Summary", "");
+    lines.push(`- Total nodes: ${input.objects.length}`);
+    lines.push(`- Total edges: ${input.edges.length}`);
+    lines.push(`- Dangling dependencies: ${dangling.length}`);
+    lines.push(`- Cross-project references: 0 (project isolation §3.0 enforced)`, "");
+    lines.push("");
+    lines.push("## §7 Cross-Stage Relations (Validation Chain)", "");
+    lines.push("### Invariant → Stage Goal Derivations", "");
+    lines.push("| Invariant | Stage | Stage Goal |");
+    lines.push("|-----------|-------|------------|");
+    for (const link of relations.derivations) {
+        lines.push(`| ${link.source_id} | ${link.target_stage} | ${link.derivation_logic} |`);
+    }
+    lines.push("");
+    lines.push("### Stage Dependencies (sequential)", "");
+    lines.push("| Upstream | Downstream | Reason |");
+    lines.push("|---------|-----------|--------|");
+    lines.push("| stage 1 (namespace) | stage 2 (puzzle) | Namespace must be set before object naming |");
+    lines.push("| stage 2 (puzzle) | stage 3 (risk) | Puzzle must be complete before risk assessment |");
+    lines.push("| stage 2 (puzzle) | stage 4 (steps) | Puzzle determines deployment step order |");
+    lines.push("| stage 3 (risk) | stage 4 (steps) | Risks must be confirmed before execution |");
+    lines.push("| stage 4 (steps) | stage 5 (substeps) | Steps must be defined before substep tracing |");
+    lines.push("");
+    lines.push("## §8 Gas / Faucet Rules", "");
+    lines.push("- testnet: gas is free (faucet) — encourage experimentation,回退无成本");
+    lines.push("- mainnet: gas is real — 回退后重跑有真实成本, WARN before rollback");
+    lines.push("- Reversibility is determined by object lifecycle (§3.2), NOT by network");
+    lines.push("");
+    lines.push("## §9 Stage Subdirectory Index", "");
+    lines.push("| Stage | Directory | README | Assessment | Risk Policy | Verification | Content |");
+    lines.push("|-------|-----------|--------|------------|-------------|--------------|---------|");
+    for (const stage of [1, 2, 3, 4, 5]) {
+        const dir = `0${stage}-${stageNames[stage]}/`;
+        lines.push(`| ${stage} | [${dir}](./${dir}) | [README.md](./${dir}README.md) | [assessment.json](./${dir}assessment.json) | [risk-policy.json](./${dir}risk-policy.json) | [verification.json](./${dir}verification.json) | [content.md](./${dir}content.md) |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderStageReadme(stage, input) {
+    const goal = STAGE_GOALS[stage];
+    const lines = [];
+    const stageNames = {
+        1: "namespace", 2: "puzzle", 3: "risk", 4: "steps", 5: "substeps",
+    };
+    lines.push(`# Stage ${stage}: ${stageNames[stage]} — ${input.project_prefix}_${input.version}`, "");
+    lines.push("> **Nested-autonomy unit**: this stage is self-governing.", "");
+    lines.push("> See [../README.md](../README.md) for project-level goals + invariants.", "");
+    lines.push("");
+    lines.push("## Stage Goal (derived from project invariants)", "");
+    lines.push(`**Statement**: ${goal.goal_statement}`, "");
+    lines.push(`**Derived from**: ${goal.derived_from.join(", ")}`, "");
+    lines.push("");
+    lines.push("### Success Criteria", "");
+    lines.push("| criterion_id | description | measurable | target |");
+    lines.push("|--------------|-------------|------------|--------|");
+    for (const c of goal.success_criteria) {
+        lines.push(`| ${c.criterion_id} | ${c.description} | ${c.measurable} | ${c.target_value ?? "-"} |`);
+    }
+    lines.push("");
+    lines.push("## Stage Files", "");
+    lines.push("- `assessment.json` — stage assessment (completion per criterion)");
+    lines.push("- `risk-policy.json` — stage-specific risks + controls");
+    lines.push("- `verification.json` — stage verification (goal + D-checks + cross-stage)");
+    lines.push("- `content.md` — stage content (actual deployment data)");
+    lines.push("");
+    return lines.join("\n");
+}
+export function generateDeploymentDocSet(prefix, version, input) {
+    if (input.project_prefix !== prefix) {
+        throw new Error(`generateDeploymentDocSet: input.project_prefix (${input.project_prefix}) does not match prefix (${prefix})`);
+    }
+    if (input.version !== version) {
+        throw new Error(`generateDeploymentDocSet: input.version (${input.version}) does not match version (${version})`);
+    }
+    const depDir = deploymentDir(prefix, version);
+    ensureProjectDir(prefix, version);
+    const relations = generateValidationChainGraph(input);
+    const allFiles = [];
+    const stageDirs = {
+        1: "", 2: "", 3: "", 4: "", 5: "",
+    };
+    const stageNames = {
+        1: "namespace", 2: "puzzle", 3: "risk", 4: "steps", 5: "substeps",
+    };
+    let allStagesPassed = true;
+    for (const stage of [1, 2, 3, 4, 5]) {
+        const stageDir = `deployment/0${stage}-${stageNames[stage]}`;
+        stageDirs[stage] = join(depDir, `0${stage}-${stageNames[stage]}`);
+        const readmeMd = renderStageReadme(stage, input);
+        saveProjectMarkdown(prefix, version, `${stageDir}/README.md`, readmeMd);
+        allFiles.push(`${stageDir}/README.md`);
+        const assessment = generateStageAssessment(stage, input);
+        saveProjectFile(prefix, version, `${stageDir}/assessment.json`, assessment);
+        allFiles.push(`${stageDir}/assessment.json`);
+        const riskPolicy = STAGE_RISK_POLICIES[stage];
+        saveProjectFile(prefix, version, `${stageDir}/risk-policy.json`, riskPolicy);
+        allFiles.push(`${stageDir}/risk-policy.json`);
+        const verification = generateStageVerification(stage, input);
+        if (!verification.stage_passed)
+            allStagesPassed = false;
+        saveProjectFile(prefix, version, `${stageDir}/verification.json`, verification);
+        allFiles.push(`${stageDir}/verification.json`);
+        const contentMd = STAGE_CONTENT_RENDERERS[stage](input);
+        saveProjectMarkdown(prefix, version, `${stageDir}/content.md`, contentMd);
+        allFiles.push(`${stageDir}/content.md`);
+    }
+    const readmeMd = renderProjectReadme(input, relations);
+    saveProjectMarkdown(prefix, version, "deployment/README.md", readmeMd);
+    allFiles.push("deployment/README.md");
+    saveProjectFile(prefix, version, "deployment/relations.json", relations);
+    allFiles.push("deployment/relations.json");
+    return {
+        readme_path: join(depDir, "README.md"),
+        relations_path: join(depDir, "relations.json"),
+        stage_dirs: stageDirs,
+        all_files: allFiles,
+        relations,
+        all_stages_passed: allStagesPassed,
+    };
+}