forgecraft-mcp 1.3.2 → 1.6.1

package/dist/tools/probe-templates.js

@@ -0,0 +1,279 @@
+/**
+ * Probe content template generators for generate_harness.
+ * Each function returns the file content for a given probe type.
+ */
+// ── Template generators ───────────────────────────────────────────────
+export function generatePlaywrightProbe(ucId, title, precondition, postcondition, steps, scenario = "happy") {
+    const stepComments = steps.length > 0
+        ? steps.map((s, i) => `    // Step ${i + 1}: ${s}`).join("\n")
+        : `    // TODO: implement ${ucId} main flow steps`;
+    return `import { test, expect } from '@playwright/test';
+
+/**
+ * L2 Harness: ${ucId} — ${title} [${scenario}]
+ * Precondition: ${precondition}
+ * Postcondition: ${postcondition}
+ */
+test.describe('${ucId}: ${title}', () => {
+  test('postcondition: ${postcondition}', async ({ page }) => {
+${stepComments}
+    throw new Error('Probe not yet implemented — fill in the ${ucId} flow');
+  });
+});
+`;
+}
+export function generateHurlProbe(ucId, title, precondition, postcondition, steps, scenario = "happy") {
+    const stepComments = steps.length > 0
+        ? steps.map((s, i) => `# Step ${i + 1}: ${s}`).join("\n")
+        : `# TODO: implement ${ucId} main flow steps`;
+    return `# L2 Harness: ${ucId} — ${title} [${scenario}]
+# Precondition: ${precondition}
+# Postcondition: ${postcondition}
+${stepComments}
+POST http://{{host}}/api/endpoint
+Content-Type: application/json
+{ "field": "value" }
+HTTP 200
+`;
+}
+export function generateGraphqlHurlProbe(ucId, title, postcondition, scenario = "happy") {
+    return `# L2 Harness: ${ucId} — ${title} [${scenario}]
+# GraphQL postcondition: ${postcondition}
+POST http://{{host}}/graphql
+Content-Type: application/json
+{ "query": "query { __typename }", "variables": {} }
+HTTP 200
+[Asserts]
+jsonpath "$.data" exists
+`;
+}
+export function generateShProbe(ucId, title, postcondition, probeType, scenario = "happy") {
+    if (probeType === "mcp_call") {
+        return `#!/usr/bin/env bash
+# L2 Harness: ${ucId} — ${title} [${scenario}]
+# Verifies MCP action postconditions
+set -euo pipefail
+echo "TODO: implement ${ucId} MCP probe"
+exit 1
+`;
+    }
+    return `#!/usr/bin/env bash
+# L2 Harness: ${ucId} — ${title} [${scenario}]
+# Postcondition: ${postcondition}
+set -euo pipefail
+echo "PASS: ${ucId} postcondition verified"
+`;
+}
+export function generateDbShProbe(ucId, title, postcondition, scenario = "happy") {
+    return `#!/usr/bin/env bash
+# L2 Harness: ${ucId} — ${title} [${scenario}]
+# DB postcondition: ${postcondition}
+set -euo pipefail
+DB_URL="\${DATABASE_URL:-}"
+if [ -z "$DB_URL" ]; then
+  echo "SKIP: DATABASE_URL not set — cannot verify DB postcondition"
+  exit 0
+fi
+echo "TODO: implement DB postcondition check for ${ucId} [${scenario}]"
+exit 1
+`;
+}
+export function generateMqShProbe(ucId, title, postcondition, scenario = "happy") {
+    return `#!/usr/bin/env bash
+# L2 Harness: ${ucId} — ${title} [${scenario}]
+# Queue postcondition: ${postcondition}
+set -euo pipefail
+BROKER="\${KAFKA_BROKER:?KAFKA_BROKER is required}"
+TOPIC="\${QUEUE_TOPIC:-}"
+if command -v kcat &>/dev/null; then
+  echo "TODO: assert event published to $TOPIC via kcat"
+  exit 1
+elif command -v rabbitmqadmin &>/dev/null; then
+  echo "TODO: rabbitmqadmin get queue={{queue_name}}"
+  exit 1
+else
+  echo "SKIP: no queue inspection tool found (kcat, rabbitmqadmin)"
+  exit 0
+fi
+`;
+}
+export function generateK6Probe(ucId, title, postcondition, scenario = "happy") {
+    return `// L2 Harness: ${ucId} — ${title} [${scenario}]
+// NFR contract: ${postcondition}
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+export const options = {
+  vus: 10,
+  duration: '30s',
+  thresholds: {
+    http_req_duration: ['p(99)<500'],
+    http_req_failed: ['rate<0.01'],
+  },
+};
+export default function () {
+  const res = http.get(__ENV.API_URL + '/api/health');
+  check(res, { 'status is 200': (r) => r.status === 200 });
+  sleep(1);
+}
+`;
+}
+export function generateWsShProbe(ucId, title, postcondition, scenario = "happy") {
+    return `#!/usr/bin/env bash
+# L2 Harness: ${ucId} — ${title} [${scenario}]
+# WebSocket postcondition: ${postcondition}
+set -euo pipefail
+WS_URL="\${WS_URL:?WS_URL is required}"
+if command -v wscat &>/dev/null; then
+  echo "TODO: assert WebSocket message for ${ucId} [${scenario}]"
+  exit 1
+else
+  echo "SKIP: wscat not found (npm install -g wscat)"
+  exit 0
+fi
+`;
+}
+export function generateLogShProbe(ucId, title, _postcondition, scenario = "happy") {
+    return `#!/usr/bin/env bash
+# L2 Harness: ${ucId} — ${title} [${scenario}]
+# Log postcondition: structured log entry must appear after use case execution
+set -euo pipefail
+LOG_FILE="\${LOG_FILE:-/tmp/app.log}"
+EXPECTED_PATTERN="\${LOG_PATTERN:-${ucId}}"
+echo "TODO: implement log assertion for ${ucId} [${scenario}]"
+exit 1
+`;
+}
+export function generateA11yProbe(ucId, title) {
+    return `import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+/**
+ * L2 Harness: ${ucId} — ${title} [Accessibility]
+ * Contract: Zero WCAG 2.1 AA violations on the primary use case page.
+ */
+test.describe('${ucId} Accessibility: ${title}', () => {
+  test('WCAG 2.1 AA — zero violations', async ({ page }) => {
+    await page.goto(process.env['BASE_URL'] ?? '');
+    const results = await new AxeBuilder({ page })
+      .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
+      .analyze();
+    expect(results.violations).toEqual([]);
+  });
+});
+`;
+}
+export function generateConsumerContractProbe(ucId, title) {
+    return `import { PactV3 } from '@pact-foundation/pact';
+import { join } from 'path';
+
+/**
+ * L2 Harness: ${ucId} — ${title} [Consumer Contract]
+ */
+const provider = new PactV3({
+  consumer: '{{consumer_name}}',
+  provider: '{{provider_name}}',
+  dir: join(__dirname, '../../pacts'),
+});
+describe('${ucId} Consumer Contract', () => {
+  it('has a valid interaction for ${title}', async () => {
+    throw new Error('Not implemented: define the Pact interaction for ${ucId}');
+  });
+});
+`;
+}
+export function generateProviderContractProbe(ucId, title) {
+    return `import { Verifier } from '@pact-foundation/pact';
+import { join } from 'path';
+
+/**
+ * L2 Harness: ${ucId} — ${title} [Provider Verification]
+ */
+describe('${ucId} Provider Verification', () => {
+  it('satisfies all consumer contracts', async () => {
+    return new Verifier({
+      provider: '{{provider_name}}',
+      providerBaseUrl: process.env.PROVIDER_URL ?? 'http://localhost:3000',
+      pactUrls: [join(__dirname, '../../pacts')],
+    }).verifyProvider();
+  });
+});
+`;
+}
+export function generateGrpcShProbe(ucId, title, postcondition, scenario = "happy") {
+    return `#!/usr/bin/env bash
+# L2 Harness: ${ucId} — ${title} [${scenario}]
+# gRPC postcondition: ${postcondition}
+set -euo pipefail
+GRPC_HOST="\${GRPC_HOST:?GRPC_HOST is required}"
+if ! command -v grpcurl &>/dev/null; then
+  echo "SKIP: grpcurl not found (brew install grpcurl)"
+  exit 0
+fi
+echo "TODO: implement gRPC probe for ${ucId} [${scenario}]"
+exit 1
+`;
+}
+export function generateZapShProbe(ucId, title) {
+    return `#!/usr/bin/env bash
+# L2 Harness: ${ucId} — ${title} [Security Scan]
+# Contract: zero HIGH/CRITICAL vulnerabilities on the use case endpoint.
+set -euo pipefail
+TARGET_URL="\${TARGET_URL:?TARGET_URL is required}"
+if ! command -v docker &>/dev/null; then
+  echo "SKIP: docker not found — cannot run OWASP ZAP scan"
+  exit 0
+fi
+docker run --rm -t owasp/zap2docker-stable \\
+  zap-baseline.py -t "$TARGET_URL" -l WARN --exit-code true 2>&1 || {
+    echo "FAIL: ZAP found vulnerabilities on $TARGET_URL"
+    exit 1
+  }
+`;
+}
+export function generateSimProbe(ucId, title) {
+    return `/**
+ * L2 Harness: ${ucId} — ${title}
+ * Headless simulation probe — verifies behavioral invariants without rendering.
+ */
+throw new Error('Probe not yet implemented — implement the ${ucId} simulation scenario');
+`;
+}
+export function generateProbeContent(ucId, title, probeType, details, scenario = "happy") {
+    switch (probeType) {
+        case "playwright":
+            return generatePlaywrightProbe(ucId, title, details.precondition, details.postcondition, details.steps, scenario);
+        case "api_call":
+        case "hurl":
+            return generateHurlProbe(ucId, title, details.precondition, details.postcondition, details.steps, scenario);
+        case "graphql":
+            return generateGraphqlHurlProbe(ucId, title, details.postcondition, scenario);
+        case "headless_sim":
+            return generateSimProbe(ucId, title);
+        case "db_query":
+            return generateDbShProbe(ucId, title, details.postcondition, scenario);
+        case "message_queue":
+            return generateMqShProbe(ucId, title, details.postcondition, scenario);
+        case "performance":
+            return generateK6Probe(ucId, title, details.postcondition, scenario);
+        case "websocket":
+            return generateWsShProbe(ucId, title, details.postcondition, scenario);
+        case "log_assertion":
+            return generateLogShProbe(ucId, title, details.postcondition, scenario);
+        case "a11y":
+            return generateA11yProbe(ucId, title);
+        case "contract_consumer":
+            return generateConsumerContractProbe(ucId, title);
+        case "contract_provider":
+            return generateProviderContractProbe(ucId, title);
+        case "grpc":
+            return generateGrpcShProbe(ucId, title, details.postcondition, scenario);
+        case "security_scan":
+            return generateZapShProbe(ucId, title);
+        case "mcp_call":
+            return generateShProbe(ucId, title, details.postcondition, "mcp_call", scenario);
+        case "file_system":
+        default:
+            return generateShProbe(ucId, title, details.postcondition, "file_system", scenario);
+    }
+}
+//# sourceMappingURL=probe-templates.js.map

package/dist/tools/probe-templates.js.map

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

package/dist/tools/propose-session.d.ts

@@ -0,0 +1,28 @@
+/**
+ * propose_session tool handler.
+ *
+ * Produces a pre-implementation impact assessment before generate_session_prompt runs.
+ * Adapted from OpenSpec's Propose phase, extended with forgecraft's layer-awareness.
+ *
+ * Output: which specs will change (ADDED/MODIFIED), which layers are affected,
+ * which gates must pass before close_cycle, and an implementation checklist.
+ * Writes .forgecraft/proposal.md as a persistent artifact.
+ */
+import { z } from "zod";
+import type { ToolResult } from "../shared/types.js";
+export declare const proposeSessionSchema: z.ZodObject<{
+    project_dir: z.ZodString;
+    item_description: z.ZodOptional<z.ZodString>;
+    roadmap_item_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    project_dir: string;
+    item_description?: string | undefined;
+    roadmap_item_id?: string | undefined;
+}, {
+    project_dir: string;
+    item_description?: string | undefined;
+    roadmap_item_id?: string | undefined;
+}>;
+export type ProposeSessionInput = z.infer<typeof proposeSessionSchema>;
+export declare function proposeSessionHandler(args: ProposeSessionInput): Promise<ToolResult>;
+//# sourceMappingURL=propose-session.d.ts.map

package/dist/tools/propose-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propose-session.d.ts","sourceRoot":"","sources":["../../src/tools/propose-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAMrD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAe/B,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAqBvE,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,UAAU,CAAC,CAqDrB"}

package/dist/tools/propose-session.js

@@ -0,0 +1,333 @@
+/**
+ * propose_session tool handler.
+ *
+ * Produces a pre-implementation impact assessment before generate_session_prompt runs.
+ * Adapted from OpenSpec's Propose phase, extended with forgecraft's layer-awareness.
+ *
+ * Output: which specs will change (ADDED/MODIFIED), which layers are affected,
+ * which gates must pass before close_cycle, and an implementation checklist.
+ * Writes .forgecraft/proposal.md as a persistent artifact.
+ */
+import { z } from "zod";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseUseCases } from "./layer-status.js";
+import { detectClarificationMarkers } from "./session-prompt-builders.js";
+// ── Schema ────────────────────────────────────────────────────────────
+export const proposeSessionSchema = z.object({
+    project_dir: z.string().describe("Absolute path to the project root."),
+    item_description: z
+        .string()
+        .min(10)
+        .optional()
+        .describe("What this session should build or fix. One sentence with actor, behavior, and postcondition."),
+    roadmap_item_id: z
+        .string()
+        .optional()
+        .describe("Roadmap item ID to propose for (e.g. 'RM-001'). Reads title from docs/roadmap.md."),
+});
+// ── Handler ──────────────────────────────────────────────────────────
+export async function proposeSessionHandler(args) {
+    const projectDir = resolve(args.project_dir);
+    let itemDescription = args.item_description;
+    if (!itemDescription && args.roadmap_item_id) {
+        itemDescription =
+            resolveRoadmapTitle(projectDir, args.roadmap_item_id) ?? undefined;
+    }
+    if (!itemDescription) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "## Proposal Blocked\n\nProvide `item_description` or a valid `roadmap_item_id`.",
+                },
+            ],
+        };
+    }
+    const useCases = loadUseCases(projectDir);
+    const relatedUcIds = matchRelatedUcs(itemDescription, useCases);
+    const specDelta = buildSpecDelta(projectDir, itemDescription, relatedUcIds, useCases);
+    const gateRequirements = loadRequiredGates(projectDir);
+    const clarifications = detectClarificationMarkers(projectDir);
+    const layerSummary = buildLayerSummary(projectDir, relatedUcIds, useCases);
+    const checklist = buildChecklist(projectDir, itemDescription, specDelta, relatedUcIds);
+    const proposal = renderProposal({
+        projectDir,
+        itemDescription,
+        specDelta,
+        layerSummary,
+        gateRequirements,
+        clarifications,
+        checklist,
+    });
+    const forgecraftDir = join(projectDir, ".forgecraft");
+    mkdirSync(forgecraftDir, { recursive: true });
+    writeFileSync(join(forgecraftDir, "proposal.md"), proposal, "utf-8");
+    return { content: [{ type: "text", text: proposal }] };
+}
+// ── Use Case Matching ─────────────────────────────────────────────────
+function loadUseCases(projectDir) {
+    const path = join(projectDir, "docs", "use-cases.md");
+    if (!existsSync(path))
+        return [];
+    try {
+        return parseUseCases(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+function matchRelatedUcs(description, ucs) {
+    if (ucs.length === 0)
+        return [];
+    const lower = description.toLowerCase();
+    const words = lower.split(/\s+/).filter((w) => w.length > 3);
+    return ucs
+        .filter((uc) => {
+        const title = uc.title.toLowerCase();
+        return words.some((w) => title.includes(w));
+    })
+        .map((uc) => uc.id);
+}
+// ── Spec Delta ────────────────────────────────────────────────────────
+function buildSpecDelta(projectDir, description, relatedUcIds, ucs) {
+    const deltas = [];
+    // Use cases
+    if (existsSync(join(projectDir, "docs", "use-cases.md"))) {
+        if (relatedUcIds.length > 0) {
+            deltas.push({
+                artifact: "docs/use-cases.md",
+                change: "MODIFIED",
+                reason: `Affects use case(s): ${relatedUcIds.join(", ")}`,
+            });
+        }
+        else if (ucs.length > 0) {
+            deltas.push({
+                artifact: "docs/use-cases.md",
+                change: "MODIFIED",
+                reason: "May require a new use case entry for this session",
+            });
+        }
+    }
+    else {
+        deltas.push({
+            artifact: "docs/use-cases.md",
+            change: "ADDED",
+            reason: "Use cases file does not exist — create before implementing",
+        });
+    }
+    // PRD
+    if (!existsSync(join(projectDir, "docs", "PRD.md"))) {
+        deltas.push({
+            artifact: "docs/PRD.md",
+            change: "ADDED",
+            reason: "Product requirements not found — run setup_project",
+        });
+    }
+    else {
+        deltas.push({
+            artifact: "docs/PRD.md",
+            change: "MODIFIED",
+            reason: "Requirement coverage may need updating after session",
+        });
+    }
+    // ADR — check if a related ADR likely exists
+    const adrHint = needsAdr(description);
+    if (adrHint) {
+        deltas.push({
+            artifact: "docs/adrs/NNNN-<decision-slug>.md",
+            change: "ADDED",
+            reason: adrHint,
+        });
+    }
+    // Session prompt
+    deltas.push({
+        artifact: ".forgecraft/proposal.md",
+        change: "ADDED",
+        reason: "This proposal (written now)",
+    });
+    return deltas;
+}
+function needsAdr(description) {
+    const triggers = [
+        ["database", "DB", "storage", "schema", "migration"],
+        ["auth", "authentication", "authorization", "JWT", "token"],
+        ["api", "endpoint", "REST", "GraphQL", "gRPC"],
+        ["cache", "Redis", "CDN"],
+        ["queue", "event", "message", "Kafka", "SQS"],
+        ["deploy", "infrastructure", "IaC", "container", "Docker", "Kubernetes"],
+    ];
+    const lower = description.toLowerCase();
+    for (const group of triggers) {
+        if (group.some((kw) => lower.includes(kw.toLowerCase()))) {
+            return `Decision involves ${group[0]} — likely needs an ADR before committing`;
+        }
+    }
+    return null;
+}
+// ── Gate Loading ──────────────────────────────────────────────────────
+function loadRequiredGates(projectDir) {
+    const dirs = [
+        join(projectDir, ".forgecraft", "gates", "active"),
+        join(projectDir, ".forgecraft", "gates", "project", "active"),
+    ];
+    const gates = [];
+    for (const dir of dirs) {
+        if (!existsSync(dir))
+            continue;
+        try {
+            for (const f of readdirSync(dir).filter((n) => n.endsWith(".yaml"))) {
+                const gate = parseGateYaml(join(dir, f));
+                if (gate)
+                    gates.push(gate);
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return gates;
+}
+function parseGateYaml(filePath) {
+    try {
+        const text = readFileSync(filePath, "utf-8");
+        const id = /^id:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "";
+        const description = /^description:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "";
+        const priority = /^priority:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "P2";
+        const layer = /^layer:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "L1";
+        if (!id)
+            return null;
+        return { gateId: id, description, priority, layer };
+    }
+    catch {
+        return null;
+    }
+}
+function buildLayerSummary(projectDir, relatedUcIds, ucs) {
+    const harnessDir = join(projectDir, "tests", "harness");
+    const envDir = join(projectDir, "tests", "env");
+    const sloDir = join(projectDir, "tests", "slo");
+    const candidates = relatedUcIds.length > 0
+        ? ucs.filter((uc) => relatedUcIds.includes(uc.id))
+        : ucs.slice(0, 5); // show first 5 if no match
+    return candidates.map((uc) => {
+        const lower = uc.id.toLowerCase().replace(/_/g, "-");
+        const l2 = existsSync(harnessDir) &&
+            readdirSync(harnessDir).some((f) => f.toLowerCase().startsWith(lower))
+            ? "✅ probes found"
+            : "❌ no probes";
+        const l3 = existsSync(envDir) &&
+            readdirSync(envDir).some((f) => f.toLowerCase().startsWith(lower))
+            ? "✅ env probes"
+            : "—";
+        const l4 = existsSync(sloDir) &&
+            readdirSync(sloDir).some((f) => f.toLowerCase().startsWith(lower))
+            ? "✅ slo probes"
+            : "—";
+        const l1 = existsSync(join(projectDir, "docs", "use-cases.md"))
+            ? "✅ use case"
+            : "❌ missing";
+        return { ucId: uc.id, title: uc.title, l1, l2, l3, l4 };
+    });
+}
+// ── Checklist ─────────────────────────────────────────────────────────
+function buildChecklist(projectDir, _description, specDelta, relatedUcIds) {
+    const items = [];
+    // Cascade check
+    items.push("Run `check_cascade` — all 5 steps must be complete before starting");
+    // Clarifications
+    items.push("Resolve all `[NEEDS CLARIFICATION]` markers in spec artifacts");
+    // Spec updates
+    const added = specDelta.filter((d) => d.change === "ADDED");
+    if (added.length > 0) {
+        for (const d of added) {
+            items.push(`Create missing artifact: \`${d.artifact}\` — ${d.reason}`);
+        }
+    }
+    // Harness
+    if (relatedUcIds.length > 0) {
+        items.push(`Run \`generate_harness\` for affected use cases: ${relatedUcIds.join(", ")}`);
+        items.push("Implement harness probe TODO sections before closing");
+    }
+    // TDD loop
+    items.push("Write failing probes first, then implement until green");
+    items.push("Run `run_harness` — all L2 probes must pass before `close_cycle`");
+    // Env / infra check
+    if (existsSync(join(projectDir, "tests", "env"))) {
+        items.push("Run `run_env_probe` — L3 env contracts must hold after changes");
+    }
+    // Close
+    items.push("Run `close_cycle` — evaluates all gates and writes `.claude/state.md`");
+    items.push("Update `Status.md` with completed changes and next steps");
+    return items;
+}
+// ── Roadmap Resolution ────────────────────────────────────────────────
+function resolveRoadmapTitle(projectDir, itemId) {
+    const path = join(projectDir, "docs", "roadmap.md");
+    if (!existsSync(path))
+        return null;
+    const text = readFileSync(path, "utf-8");
+    const re = new RegExp(`\\|\\s*${itemId}\\s*\\|[^|]+\\|([^|]+)\\|`);
+    const m = re.exec(text);
+    return m ? (m[1]?.trim() ?? null) : null;
+}
+function renderProposal(input) {
+    const { itemDescription, specDelta, layerSummary, gateRequirements, clarifications, checklist, } = input;
+    const date = new Date().toISOString().slice(0, 10);
+    const lines = [];
+    lines.push(`# Session Proposal`, ``, `**Date:** ${date}`, `**Scope:** ${itemDescription}`, ``);
+    lines.push(`> This proposal is a pre-implementation impact assessment.`);
+    lines.push(`> Resolve all blockers, then run \`generate_session_prompt\` to commit to implementation.`, ``);
+    // Spec delta
+    lines.push(`## Spec Delta`, ``);
+    lines.push(`| Artifact | Change | Reason |`, `|---|---|---|`);
+    for (const d of specDelta) {
+        const badge = d.change === "ADDED"
+            ? "🆕 ADDED"
+            : d.change === "MODIFIED"
+                ? "✏️ MODIFIED"
+                : "🗑 REMOVED";
+        lines.push(`| \`${d.artifact}\` | ${badge} | ${d.reason} |`);
+    }
+    lines.push(``);
+    // Layer readiness
+    if (layerSummary.length > 0) {
+        lines.push(`## Layer Readiness — Affected Use Cases`, ``);
+        lines.push(`| UC | Title | L1 Spec | L2 Probes | L3 Env | L4 SLO |`, `|---|---|---|---|---|---|`);
+        for (const r of layerSummary) {
+            lines.push(`| ${r.ucId} | ${r.title} | ${r.l1} | ${r.l2} | ${r.l3} | ${r.l4} |`);
+        }
+        lines.push(``);
+    }
+    else {
+        lines.push(`## Layer Readiness`, ``, `_No use cases found. Run \`setup_project\` to create the spec foundation._`, ``);
+    }
+    // Clarifications
+    if (clarifications.length > 0) {
+        lines.push(`## ⚠️ Unresolved Clarifications — Must Resolve Before Session`, ``);
+        lines.push(`| File | Marker |`, `|---|---|`);
+        for (const c of clarifications) {
+            lines.push(`| \`${c.file}\` | ${c.marker} |`);
+        }
+        lines.push(``, `Resolve these before running \`generate_session_prompt\`.`, ``);
+    }
+    // Gates
+    if (gateRequirements.length > 0) {
+        lines.push(`## Gates That Must Pass Before \`close_cycle\``, ``);
+        lines.push(`| Gate ID | Layer | Priority | Description |`, `|---|---|---|---|`);
+        for (const g of gateRequirements) {
+            lines.push(`| ${g.gateId} | ${g.layer} | ${g.priority} | ${g.description} |`);
+        }
+        lines.push(``);
+    }
+    // Checklist
+    lines.push(`## Pre-Implementation Checklist`, ``);
+    for (const item of checklist) {
+        lines.push(`- [ ] ${item}`);
+    }
+    lines.push(``);
+    lines.push(`---`);
+    lines.push(`_Proposal written to \`.forgecraft/proposal.md\`. Run \`generate_session_prompt\` when ready to commit._`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=propose-session.js.map