forgecraft-mcp 1.4.0 → 1.7.0

package/dist/tools/setup-monitoring.js

@@ -0,0 +1,364 @@
+/**
+ * setup_monitoring tool handler.
+ *
+ * Generates docs/monitoring-spec.md from the project's NFR contracts and
+ * behavioral contracts. This is the production contract that forgecraft-eye
+ * evaluates runtime signals against at T4.
+ *
+ * The generated spec contains:
+ *   - Exception classes that signal specification drift
+ *   - Alert thresholds with exact numeric criteria
+ *   - SLO definitions for each service
+ *   - Correlation ID and PII redaction policy
+ *   - Property violation mapping (exception → GS property → spec location)
+ */
+import { z } from "zod";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+// ── Schema ───────────────────────────────────────────────────────────
+export const setupMonitoringSchema = z.object({
+    project_dir: z.string().describe("Absolute path to the project root."),
+    project_name: z
+        .string()
+        .optional()
+        .describe("Project name for the spec header. Inferred from directory name if omitted."),
+    force: z
+        .boolean()
+        .optional()
+        .describe("Overwrite existing monitoring-spec.md. Default: false."),
+});
+// ── Source doc paths ─────────────────────────────────────────────────
+const SOURCE_DOCS = [
+    "docs/nfr-contracts.md",
+    "docs/behavioral-contracts.md",
+    "docs/use-cases.md",
+    "docs/PRD.md",
+];
+// ── Template ─────────────────────────────────────────────────────────
+function buildMonitoringSpec(projectName, nfrContent, behavioralContent) {
+    const date = new Date().toISOString().slice(0, 10);
+    const nfrSection = nfrContent ? extractNfrExceptionClasses(nfrContent) : null;
+    return `# Monitoring Specification — ${projectName}
+<!-- Generated by forgecraft setup_monitoring on ${date} -->
+<!-- This document is the T4 production contract. -->
+<!-- forgecraft-eye evaluates runtime signals against these definitions. -->
+<!-- DO NOT state thresholds as "when errors are high" — use exact numeric criteria. -->
+
+---
+
+## 1. Exception Classes
+
+Exception classes that signal specification drift. Only exceptions listed here
+trigger T4 diagnostic evaluation — not all exceptions, not error volume.
+
+| Exception Class | Severity | GS Property Violated | Spec Location | Chronicle Tag |
+|---|---|---|---|---|
+${nfrSection?.exceptionRows ?? "| TODO_ExceptionClass | critical | Verifiable | docs/behavioral-contracts.md#TODO | t4-signal |"}
+
+**Instructions:** For each exception class:
+1. State the fully-qualified class name (e.g., \`PaymentRetryExhaustedException\`)
+2. Assign severity: \`critical\` (T4 immediate), \`warning\` (T4 batched), \`info\` (T4 aggregate)
+3. Map to the GS property it violates: Verifiable, Auditable, Defended, Composable, etc.
+4. Reference the exact use case postcondition or invariant in the spec
+
+---
+
+## 2. Alert Thresholds
+
+SLO alert definitions with exact numeric criteria. Thresholds stated as
+"when errors are high" are invalid — the diagnostic agent cannot act on them.
+
+| Alert Name | Metric | Condition | Duration | Severity | NFR Source |
+|---|---|---|---|---|---|
+${nfrSection?.alertRows ?? "| error_rate_high | http_request_errors_total / http_requests_total | > 0.005 | 5m | page | NFR-TODO |"}
+
+**Instructions:** Every threshold must be:
+- Numeric (exact value, not "high" or "low")
+- Time-bounded (window: 1m, 5m, 15m, 1h)
+- Tied to an NFR contract identifier (NFR-01, NFR-02, etc.)
+
+---
+
+## 3. SLO Definitions
+
+PromQL (or equivalent) queries for each service-level objective.
+
+\`\`\`yaml
+# Service: TODO_service_name
+# NFR source: docs/nfr-contracts.md#TODO
+slos:
+  - id: availability
+    query: "sum(rate(http_requests_total{job=\"TODO\",code!~\"5..\"}[5m])) / sum(rate(http_requests_total{job=\"TODO\"}[5m]))"
+    threshold: 0.999
+    operator: ">="
+    window: "30d"
+    alert_name: TODO_AvailabilityBreach
+
+  - id: p95_latency
+    query: "histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket{job=\"TODO\"}[5m])) by (le))"
+    threshold: 0.5
+    operator: "<="
+    window: "1h"
+    alert_name: TODO_LatencyBreach
+\`\`\`
+
+---
+
+## 4. Correlation ID Schema
+
+How requests are traced end-to-end through the system. Required for T4 diagnosis
+to correlate an exception with its originating request context.
+
+\`\`\`
+Header: X-Correlation-ID
+Format: UUID v4
+Propagation: all outbound service calls, all log entries, all exception payloads
+Example: X-Correlation-ID: 550e8400-e29b-41d4-a716-446655440000
+\`\`\`
+
+**Log format requirement:**
+\`\`\`json
+{
+  "timestamp": "ISO-8601",
+  "level": "ERROR|WARN|INFO",
+  "correlation_id": "UUID",
+  "service": "service-name",
+  "exception_class": "FullyQualifiedExceptionClass",
+  "message": "human-readable description",
+  "spec_ref": "docs/behavioral-contracts.md#use-case-id"
+}
+\`\`\`
+
+---
+
+## 5. PII Redaction Policy
+
+What must never appear in logs or exception payloads.
+
+| Field Category | Examples | Action |
+|---|---|---|
+| Identity | email, full_name, national_id | Redact — replace with \`[REDACTED]\` |
+| Authentication | password, token, API key | Never log |
+| Financial | card number, account number | Mask — last 4 digits only |
+| Medical | diagnosis, prescription | Redact |
+| Location | GPS coordinates, IP address | Anonymize — country-level only |
+
+**Implementation:** Redaction must happen at the logging layer, not downstream.
+If a field appears unredacted in a log entry, it is a Defended property violation.
+
+---
+
+## 6. Property Violation Mapping
+
+Maps production signals to the GS properties they violate. Used by forgecraft-eye
+to classify diagnoses before writing to Chronicle.
+
+| Exception Pattern | GS Property | Diagnosis Template |
+|---|---|---|
+| \`*RetryExhausted*\` | Verifiable | "Retry contract does not cover [exception context]. Update use case postcondition." |
+| \`*AuthorizationFailed*\` | Defended | "Authorization invariant violated at [endpoint]. Verify boundary guard in spec." |
+| \`*ValidationException*\` | Verifiable | "Input contract incomplete — [field] not covered by precondition." |
+| \`*TimeoutException*\` | Verifiable | "Timeout contract missing for [service call]. Add NFR SLO threshold." |
+| \`*NullPointer*\` \| \`*undefined*\` | Verifiable | "Null postcondition not stated — [component] assumes non-null without contract." |
+| \`*SchemaValidation*\` | Self-describing | "Schema contract outdated — regenerate from current spec." |
+
+---
+
+## 7. T4 Signal Queue
+
+forgecraft-eye writes signals to \`.forgecraft/t4-signals.json\`.
+Run \`forgecraft check_t4\` at session start to surface pending spec updates.
+
+\`\`\`json
+{
+  "signals": [
+    {
+      "id": "sig-YYYYMMDD-HHMMSS-001",
+      "timestamp": "ISO-8601",
+      "exception_class": "FullyQualifiedExceptionClass",
+      "severity": "critical|warning|info",
+      "gs_property": "Verifiable|Auditable|Defended|Composable|Executable|Self-describing|Bounded",
+      "spec_ref": "docs/behavioral-contracts.md#use-case-id",
+      "diagnosis": "Human-readable diagnosis text",
+      "suggested_update": "Specific spec change recommendation",
+      "status": "pending|acknowledged|resolved",
+      "correlation_id": "UUID of originating request"
+    }
+  ]
+}
+\`\`\`
+
+${behavioralContent ? "## 8. Source NFR Contracts\n\nExtracted from docs/nfr-contracts.md. Review for completeness.\n\n" + formatNfrSummary(behavioralContent) : ""}
+---
+
+*Generated by ForgeCraft T4 setup. Reviewed and extended by practitioner.*
+*forgecraft-eye config: see \`.forgecraft/eye-config.yaml\`*
+`;
+}
+// ── NFR extraction helpers ────────────────────────────────────────────
+function extractNfrExceptionClasses(nfrContent) {
+    const lines = nfrContent.split("\n");
+    // Look for existing exception class mentions
+    const exceptionLines = lines.filter((l) => l.toLowerCase().includes("exception") ||
+        l.toLowerCase().includes("error class") ||
+        l.toLowerCase().includes("failure mode"));
+    // Look for threshold mentions
+    const thresholdLines = lines.filter((l) => l.toLowerCase().includes("threshold") ||
+        l.toLowerCase().includes("slo") ||
+        l.toLowerCase().includes("availability") ||
+        l.toLowerCase().includes("latency") ||
+        (l.toLowerCase().includes("error") && l.match(/\d+%|\d+ms/)));
+    const exceptionRows = exceptionLines.length > 0
+        ? exceptionLines
+            .slice(0, 5)
+            .map((l) => `| \`${l.trim().replace(/[|]/g, "\\|")}\` | critical | Verifiable | docs/behavioral-contracts.md#TODO | t4-signal |`)
+            .join("\n")
+        : "| TODO_ExceptionClass | critical | Verifiable | docs/behavioral-contracts.md#TODO | t4-signal |";
+    const alertRows = thresholdLines.length > 0
+        ? thresholdLines
+            .slice(0, 3)
+            .map((l) => `| TODO_Alert | ${l.trim().replace(/[|]/g, "\\|")} | TODO_duration | warning | NFR-TODO |`)
+            .join("\n")
+        : "| error_rate_high | http_request_errors_total / http_requests_total | > 0.005 | 5m | page | NFR-TODO |";
+    return { exceptionRows, alertRows };
+}
+function formatNfrSummary(content) {
+    const lines = content.split("\n");
+    const relevant = lines
+        .filter((l) => l.startsWith("#") ||
+        l.toLowerCase().includes("nfr") ||
+        l.toLowerCase().includes("slo") ||
+        l.toLowerCase().includes("threshold"))
+        .slice(0, 20);
+    return (relevant.join("\n") + "\n\n*[See full file for complete NFR contracts]*\n");
+}
+// ── Eye config scaffold ──────────────────────────────────────────────
+/**
+ * Write `.forgecraft/eye-config.yaml` with sensible defaults if absent.
+ * Mirrors the shape of `EyeConfig` in forgecraft-eye without importing it.
+ *
+ * @param projectDir - Absolute path to the project root.
+ * @param projectName - Display name used for the CloudWatch log group slug.
+ * @returns `true` if the file was created, `false` if it already existed or errored.
+ */
+export function scaffoldEyeConfig(projectDir, projectName) {
+    const configPath = join(projectDir, ".forgecraft", "eye-config.yaml");
+    if (existsSync(configPath))
+        return false;
+    const slug = projectName.toLowerCase().replace(/\s+/g, "-");
+    const yaml = [
+        `# forgecraft-eye configuration — generated by forgecraft setup_monitoring`,
+        `# See: https://github.com/jghiringhelli/forgecraft-eye`,
+        ``,
+        `project_name: "${projectName}"`,
+        `project_dir: "${projectDir}"`,
+        `monitoring_spec_path: docs/monitoring-spec.md`,
+        `signal_queue_path: .forgecraft/t4-signals.json`,
+        `environment: production`,
+        `log_adapter: stdin    # options: stdin | cloudwatch`,
+        ``,
+        `# CloudWatch adapter — uncomment and set log_adapter: cloudwatch`,
+        `# cloudwatch:`,
+        `#   log_group_name: /aws/lambda/${slug}`,
+        `#   region: us-east-1`,
+        `#   filter_pattern: "?ERROR ?WARN ?Exception"`,
+    ].join("\n");
+    try {
+        mkdirSync(join(projectDir, ".forgecraft"), { recursive: true });
+        writeFileSync(configPath, yaml, "utf-8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Handler ───────────────────────────────────────────────────────────
+export async function setupMonitoringHandler(args) {
+    const projectDir = resolve(args.project_dir);
+    const force = args.force ?? false;
+    const projectName = args.project_name ?? projectDir.split(/[\\/]/).pop() ?? "Project";
+    const outputPath = join(projectDir, "docs", "monitoring-spec.md");
+    if (existsSync(outputPath) && !force) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "## Monitoring Spec Already Exists",
+                        "",
+                        `\`docs/monitoring-spec.md\` already exists at ${outputPath}.`,
+                        "Pass \`force: true\` to regenerate.",
+                        "",
+                        "Run \`forgecraft check_t4\` to surface pending T4 signals.",
+                    ].join("\n"),
+                },
+            ],
+        };
+    }
+    // Read available source docs
+    let nfrContent = null;
+    let behavioralContent = null;
+    const sourcesRead = [];
+    for (const docPath of SOURCE_DOCS) {
+        const fullPath = join(projectDir, docPath);
+        if (existsSync(fullPath)) {
+            try {
+                const content = readFileSync(fullPath, "utf-8");
+                if (docPath.includes("nfr")) {
+                    nfrContent = content;
+                    sourcesRead.push(docPath);
+                }
+                else if (docPath.includes("behavioral")) {
+                    behavioralContent = content;
+                    sourcesRead.push(docPath);
+                }
+            }
+            catch {
+                /* non-fatal — continue with template */
+            }
+        }
+    }
+    // Ensure docs/ exists
+    try {
+        mkdirSync(join(projectDir, "docs"), { recursive: true });
+    }
+    catch {
+        /* already exists */
+    }
+    const spec = buildMonitoringSpec(projectName, nfrContent, behavioralContent);
+    try {
+        writeFileSync(outputPath, spec, "utf-8");
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error writing monitoring-spec.md: ${String(err)}`,
+                },
+            ],
+        };
+    }
+    const eyeConfigCreated = scaffoldEyeConfig(projectDir, projectName);
+    const lines = [
+        "## Monitoring Spec Generated",
+        "",
+        `Generated: \`docs/monitoring-spec.md\``,
+        ...(eyeConfigCreated
+            ? [
+                "Generated: `.forgecraft/eye-config.yaml` (forgecraft-eye adapter config)",
+            ]
+            : []),
+        "",
+    ];
+    if (sourcesRead.length > 0) {
+        lines.push(`Sources read: ${sourcesRead.map((s) => `\`${s}\``).join(", ")}`);
+        lines.push("");
+    }
+    else {
+        lines.push("⚠️  No NFR contracts found — spec generated from template.", "Add `docs/nfr-contracts.md` and re-run for project-specific thresholds.", "");
+    }
+    lines.push("## Required Next Steps", "", "The generated spec contains TODO placeholders. Before T4 is operational:", "", "1. **Fill exception classes** (Section 1) — list the specific exception classes", "   that indicate specification drift in your system. Map each to the GS property", "   it violates and the spec location that governs it.", "", "2. **State exact thresholds** (Section 2) — replace all TODO_threshold values", "   with numeric criteria. 'When errors are high' is not a valid threshold.", "", "3. **Add SLO queries** (Section 3) — replace TODO PromQL queries with actual", "   metric names from your observability stack.", "", "4. **Install forgecraft-eye** — the T4 diagnostic agent that evaluates production logs", "   against your monitoring spec and writes signals to the queue.", "   ```bash", "   npm install forgecraft-eye", "   # Pipe logs in production:", "   my-service 2>&1 | npx forgecraft-eye", "   # Or invoke programmatically:", "   # import { runEyeFromConfig } from 'forgecraft-eye';", "   # await runEyeFromConfig(projectDir);", "   ```", "   npm: https://www.npmjs.com/package/forgecraft-eye", "   Source: https://github.com/jghiringhelli/forgecraft-eye", "", "5. **Run `forgecraft check_t4`** at the start of each session to surface", "   pending T4 signals from the production queue.", "", "## T4 Architecture Summary", "", "```", "Production exception fires", "  → forgecraft-eye evaluates against monitoring-spec.md", "  → writes to .forgecraft/t4-signals.json", "  → next session: forgecraft check_t4 surfaces pending signals", "  → practitioner approves spec update", "  → AI derives fix from updated specification", "  → T2 verifies, T3 deploys", "```");
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+}
+//# sourceMappingURL=setup-monitoring.js.map

package/dist/tools/setup-monitoring.js.map

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

package/dist/tools/setup-phase1.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-phase1.d.ts","sourceRoot":"","sources":["../../src/tools/setup-phase1.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EACL,kBAAkB,EAEnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIzD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,UAAU,CA2BvE;AAwKD,OAAO,EAAE,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"setup-phase1.d.ts","sourceRoot":"","sources":["../../src/tools/setup-phase1.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EACL,kBAAkB,EAEnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIzD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,UAAU,CA2BvE;AAqLD,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/tools/setup-phase1.js

@@ -54,6 +54,11 @@ function buildSpecDisambiguationBlock(candidates) {
     block += `- \`problem_statement\`: 1–3 sentence summary of the core problem the app solves\n`;
     block += `- \`primary_users\`: comma-separated list of the primary user roles or actors\n`;
     block += `- \`success_criteria\`: comma-separated list of measurable success outcomes\n\n`;
+    block += `After calling \`setup_project\`, also populate the stub docs created by setup:\n`;
+    block += `- \`docs/architecture.md\` — extract layers, components, data flow from spec\n`;
+    block += `- \`docs/data-model.md\` — extract entities and relationships from spec\n`;
+    block += `- \`docs/domain-glossary.md\` — extract domain terms from spec\n`;
+    block += `Populate these before running \`check_cascade\`.\n\n`;
     return block;
 }
 /**
@@ -64,7 +69,15 @@ function buildSpecExtractionRequest(specPath) {
     block += `Read this spec now. In your next call to \`setup_project\` (Phase 2), also provide:\n`;
     block += `- \`problem_statement\`: 1–3 sentence summary of the core problem the app solves\n`;
     block += `- \`primary_users\`: comma-separated list of the primary user roles or actors\n`;
-    block += `- \`success_criteria\`: comma-separated list of measurable success outcomes\n\n`;
+    block += `- \`success_criteria\`: comma-separated list of measurable success outcomes\n`;
+    block += `- \`use_cases\`: JSON array of the 5–12 most important use cases from the spec. Each item:\n`;
+    block += `  \`{"id":"UC-001","title":"...","actor":"...","precondition":"...","steps":["step 1","step 2"],"postcondition":"...","errorCases":[{"name":"...","description":"..."}]}\`\n`;
+    block += `\n> **Critical:** Real use cases from the spec power \`generate_harness\` (L2 probes). Generic stubs produce meaningless test scaffolding.\n\n`;
+    block += `After calling \`setup_project\` with the above parameters, also:\n`;
+    block += `4. Fill in \`docs/architecture.md\` from the spec — document layers, components, and data flow.\n`;
+    block += `5. Fill in \`docs/data-model.md\` from the spec — document all entities and relationships.\n`;
+    block += `6. Fill in \`docs/domain-glossary.md\` from the spec — define key domain terms.\n`;
+    block += `These are created as stubs by \`setup_project\`. Populate them before running \`check_cascade\`.\n\n`;
     return block;
 }
 /**

package/dist/tools/setup-phase1.js.map

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

package/dist/tools/setup-phase2.d.ts

@@ -34,6 +34,20 @@ export interface Phase2ResponseParams {
     readonly gatesIndexWritten: boolean;
     readonly gitInitStatus?: string;
     readonly isBrownfield?: boolean;
+    readonly adrsExtracted?: number;
+    readonly ucCount?: number;
+    readonly specPath?: string;
+    readonly operationClassificationWritten?: boolean;
+    readonly subDocStubsWritten?: string[];
+    readonly agentsWritten?: string[];
+    readonly manifestWritten?: boolean;
+    readonly statusWritten?: boolean;
+    /** FC QG remote gates relevant to active tags — used to generate tailoring checklist. */
+    readonly remoteGates?: readonly {
+        id: string;
+        title: string;
+        gsProperty: string;
+    }[];
 }
 /**
  * Build the phase 2 completion response.

package/dist/tools/setup-phase2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-phase2.d.ts","sourceRoot":"","sources":["../../src/tools/setup-phase2.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAc1D;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,OAAO,EACtB,YAAY,EAAE,OAAO,GACpB,eAAe,EAAE,CA8BnB;AAID,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,eAAe,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,eAAe,CAAC,EAAE,iBAAiB,GAAG,WAAW,GAAG,cAAc,CAAC;IAC5E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CA+ExE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,OAAO,EACtB,YAAY,EAAE,OAAO,GACpB,MAAM,CAYR;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,SAAS,eAAe,EAAE,GACpC,MAAM,CAeR"}
+{"version":3,"file":"setup-phase2.d.ts","sourceRoot":"","sources":["../../src/tools/setup-phase2.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAc1D;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,OAAO,EACtB,YAAY,EAAE,OAAO,GACpB,eAAe,EAAE,CA8BnB;AAID,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,eAAe,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,eAAe,CAAC,EAAE,iBAAiB,GAAG,WAAW,GAAG,cAAc,CAAC;IAC5E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,8BAA8B,CAAC,EAAE,OAAO,CAAC;IAClD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,yFAAyF;IACzF,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS;QAC9B,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACpB,EAAE,CAAC;CACL;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CA2IxE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,OAAO,EACtB,YAAY,EAAE,OAAO,GACpB,MAAM,CAYR;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,SAAS,eAAe,EAAE,GACpC,MAAM,CAeR"}

package/dist/tools/setup-phase2.js

@@ -92,8 +92,25 @@ export function buildPhase2Response(params) {
     const scaffoldFiles = extractScaffoldFiles(params.scaffoldText);
     for (const f of scaffoldFiles)
         text += `  ${f}\n`;
+    if (params.operationClassificationWritten)
+        text += `  docs/operation-classification.md (Tier 0–3 gate reference)\n`;
+    if (params.subDocStubsWritten && params.subDocStubsWritten.length > 0) {
+        for (const f of params.subDocStubsWritten)
+            text += `  ${f} (stub — populate from spec)\n`;
+    }
+    if (params.agentsWritten && params.agentsWritten.length > 0) {
+        for (const f of params.agentsWritten)
+            text += `  .claude/agents/${f} (sub-agent)\n`;
+    }
+    if (params.manifestWritten)
+        text += `  docs/manifest.yaml (GS document taxonomy contract)\n`;
+    if (params.statusWritten)
+        text += `  docs/status.md (project state — update after each session)\n`;
     if (!prdWritten && !yamlWritten && scaffoldFiles.length === 0)
         text += `  (all artifacts already existed — nothing overwritten)\n`;
+    if (params.adrsExtracted && params.adrsExtracted > 0) {
+        text += `  docs/adrs/active/ (${params.adrsExtracted} ADRs extracted from spec)\n`;
+    }
     if (params.mcpServerNames.length > 0) {
         text += `\n### MCP Tools Configured\n`;
         for (const name of params.mcpServerNames)
@@ -108,13 +125,56 @@ export function buildPhase2Response(params) {
         text += `  Fill in that file, then use it as the first acceptance test:\n`;
         text += `  the tool is done when it can produce that specific outcome.\n`;
     }
-    text += `\n### Next step — call this now:\n`;
-    text += `\`\`\`\naction: "check_cascade"\nproject_dir: "${params.projectDir ?? ""}"\n\`\`\`\n`;
+    // FC QG remote gates available for this tag set
+    if (params.remoteGates && params.remoteGates.length > 0) {
+        text += `\n### Quality Gates Available (FC QG — ${params.remoteGates.length} gates for active tags)\n`;
+        const byProperty = {};
+        for (const g of params.remoteGates) {
+            (byProperty[g.gsProperty] ??= []).push(`${g.id}: ${g.title}`);
+        }
+        for (const [prop, ids] of Object.entries(byProperty)) {
+            text += `  [${prop}] ${ids.join(", ")}\n`;
+        }
+        text += `  Run \`analyze_harness\` after setup to compare installed vs available.\n`;
+    }
     if (params.isBrownfield) {
+        text += `\n### Next step — call this now:\n`;
+        text += `\`\`\`\naction: "check_cascade"\nproject_dir: "${params.projectDir ?? ""}"\n\`\`\`\n`;
         text += `Do not ask the user — run check_cascade immediately. When it passes, run audit_project to surface any existing violations in this brownfield codebase before writing new code.`;
     }
     else {
-        text += `Do not ask the user — run check_cascade immediately. If it passes, run generate_session_prompt for the first roadmap item.`;
+        text += `\n### Greenfield artifact sequence — run in order:\n\n`;
+        if (params.ucCount && params.ucCount > 0) {
+            text += `**L1 artifacts (just created):**\n`;
+        }
+        else {
+            text += `**L1 artifacts (created — populate docs/ files from spec):**\n`;
+        }
+        text += `  ✅ forgecraft.yaml + CLAUDE.md + .claude/ + hooks\n`;
+        text += `  ✅ docs/PRD.md\n`;
+        if (params.ucCount && params.ucCount > 0) {
+            text += `  ✅ docs/use-cases.md (${params.ucCount} spec-derived use cases)\n`;
+        }
+        else {
+            text += `  ⚠ docs/use-cases.md (generic stubs — fill in real UCs from spec)\n`;
+        }
+        if (params.adrsExtracted && params.adrsExtracted > 0) {
+            text += `  ✅ docs/adrs/active/ (${params.adrsExtracted} ADRs from spec)\n`;
+        }
+        else if (params.specPath) {
+            text += `  ○ docs/adrs/active/ — run extract_adrs_from_spec to populate\n`;
+        }
+        text += `\n**Run now:**\n`;
+        text += `1. \`check_cascade\` → verifies all 5 L1 steps\n`;
+        text += `2. \`generate_roadmap\` → docs/roadmaps/active/roadmap.md (gated on cascade)\n`;
+        text += `3. \`generate_harness\` → scaffolds tests/harness/ from use cases (L2 probes)\n`;
+        text += `\n**After cascade passes:**\n`;
+        text += `4. \`generate_session_prompt\` for the first roadmap item\n`;
+        text += `5. \`analyze_harness\` → gap report vs FC QG + auto-post missing gates as issues\n`;
+        text += `\n`;
+        text += `\`\`\`\naction: "check_cascade"\nproject_dir: "${params.projectDir ?? ""}"\n\`\`\`\n`;
+        text += `Do not ask the user — run check_cascade immediately.\n\n`;
+        text += buildAiTailoringChecklist(params);
     }
     return text;
 }
@@ -151,6 +211,73 @@ export function renderCascadeDecisionsSection(decisions) {
     text += `artifacts are gated before implementation can begin.\n`;
     return text;
 }
+/**
+ * Build the AI Tailoring Checklist — the list of sentinel and harness elements
+ * that ForgeCraft cannot generate deterministically but the AI can produce
+ * immediately using its spec knowledge.
+ *
+ * These are the items that most frequently cause session degradation when absent.
+ * The AI should generate all of them NOW, before the first implementation session.
+ */
+function buildAiTailoringChecklist(params) {
+    const tags = params.tags ?? [];
+    const hasFrontend = tags.some((t) => ["WEB-REACT", "WEB-NEXT", "WEB-STATIC"].includes(t));
+    const hasApi = tags.some((t) => ["API"].includes(t));
+    let out = `### AI Tailoring Checklist — generate these NOW using spec knowledge\n\n`;
+    out += `ForgeCraft writes the structural scaffold. These items require reading your spec.\n`;
+    out += `Generate each one before the first implementation session — skipping them causes session drift.\n\n`;
+    out += `**1. Tool Sequencing Table (add to CLAUDE.md)**\n`;
+    out += `   Map every major task type to the exact tool sequence. Example:\n`;
+    out += `   | Task | Sequence |\n`;
+    out += `   |------|----------|\n`;
+    out += `   | New feature | read sentinel → check_cascade → generate_session_prompt → implement → run_harness |\n`;
+    out += `   | Bug fix | read sentinel → check_derivation_chain → fix → run_harness → change_request(bug-postmortem) |\n`;
+    out += `   Derive the actual sequences from your spec's workflow and domain.\n\n`;
+    out += `**2. Corrections Log (add to CLAUDE.md)**\n`;
+    out += `   Add a "## Corrections Log" section with format:\n`;
+    out += `   \`YYYY-MM-DD | [category] short description of AI behavioral deviation and fix\`\n`;
+    out += `   Leave it empty now — it fills up during sessions. Its presence is what matters.\n\n`;
+    out += `**3. Bound Prompts (enrich docs/use-cases.md)**\n`;
+    out += `   For each use case, add a \`### Bound Prompt\` sub-section with:\n`;
+    out += `   - **Spec refs**: which spec sections apply\n`;
+    out += `   - **Precondition**: system state required before this UC runs\n`;
+    out += `   - **Scope — what NOT to touch**: explicit exclusion list\n`;
+    out += `   - **Acceptance criteria**: measurable postconditions\n`;
+    out += `   - **Architecture constraints**: patterns/files that must be respected\n`;
+    out += `   - **Commit message format**: expected conventional commit for this UC\n\n`;
+    out += `**4. C4 Context Diagram (docs/architecture/c4-context.md)**\n`;
+    out += `   Draw the system boundary: actors, external systems, data flows.\n`;
+    out += `   Use PlantUML or Mermaid. ForgeCraft gates on architecture step — populate it.\n\n`;
+    if (hasFrontend) {
+        out += `**5. Framework Conventions (add to CLAUDE.md)**\n`;
+        const isNext = tags.includes("WEB-NEXT");
+        if (isNext) {
+            out += `   Next.js App Router specifics your sentinel must declare:\n`;
+            out += `   - RSC boundary: which components are Server vs Client (\`"use client"\` rule)\n`;
+            out += `   - Server Actions: allowed patterns, validation approach\n`;
+            out += `   - Data fetching: where async/await lives vs where it cannot\n`;
+            out += `   - Route groups, layouts, and loading.tsx ownership rules\n`;
+        }
+        else {
+            out += `   Document your frontend framework's architectural invariants.\n`;
+            out += `   Include: component ownership rules, state management boundaries, routing conventions.\n`;
+        }
+        out += `\n`;
+    }
+    if (hasApi) {
+        out += `**${hasFrontend ? 6 : 5}. API Contract Stubs (docs/api/)**\n`;
+        out += `   Even as OpenAPI stubs, declare endpoints, auth scheme, error shape.\n`;
+        out += `   These become the behavioral contracts that prevent breaking changes.\n\n`;
+    }
+    const nextNum = hasFrontend ? (hasApi ? 7 : 6) : hasApi ? 6 : 5;
+    out += `**${nextNum}. docs/status.md (session narrative)**\n`;
+    out += `   Already created with stubs. Fill in: current state, what's in progress, and "Next:" from your roadmap.\n`;
+    out += `   Update it at the end of every session. It is the project's temporal memory.\n\n`;
+    out += `**${nextNum + 1}. analyze_harness (post-scaffold gap check)**\n`;
+    out += `   Run after completing steps 1–${nextNum} to compare what exists vs what FC QG requires.\n`;
+    out += `   Missing gates are submitted as improvement proposals to the FC QG project automatically.\n`;
+    return out;
+}
 /**
  * Extract file paths listed in a scaffold response text.
  */