forgecraft-mcp 1.2.0 → 1.3.2

package/dist/tools/scaffold-spec-stubs.js

@@ -7,20 +7,20 @@
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
-export const USE_CASES_STUB = `<!-- UNFILLED: Use Cases -->
-# Use Cases
-
-## UC-01: [Name]
-**Actor**: <!-- FILL: who? -->
-**Precondition**: <!-- FILL: what must be true before? -->
-**Steps**: <!-- FILL: numbered steps -->
-**Success**: <!-- FILL: what changed? -->
-
-## UC-02: [Name]
-<!-- FILL -->
-
-## UC-03: [Name]
-<!-- FILL -->
+export const USE_CASES_STUB = `<!-- UNFILLED: Use Cases -->
+# Use Cases
+
+## UC-01: [Name]
+**Actor**: <!-- FILL: who? -->
+**Precondition**: <!-- FILL: what must be true before? -->
+**Steps**: <!-- FILL: numbered steps -->
+**Success**: <!-- FILL: what changed? -->
+
+## UC-02: [Name]
+<!-- FILL -->
+
+## UC-03: [Name]
+<!-- FILL -->
 `;
 /**
  * Build the UNFILLED stub content for docs/diagrams/c4-context.md.
@@ -29,16 +29,16 @@ export const USE_CASES_STUB = `<!-- UNFILLED: Use Cases -->
  * @returns Stub content with UNFILLED markers
  */
 export function buildC4ContextStub(projectName) {
-    return `<!-- UNFILLED: C4 Context Diagram -->
-<!-- Run \`forgecraft generate_diagram\` to auto-generate from your spec -->
-# System Context Diagram
-\`\`\`mermaid
-C4Context
-  title System Context: ${projectName}
-  Person(user, "User", "<!-- FILL: Who uses the system? -->")
-  System(system, "${projectName}", "<!-- FILL: What does the system do in one sentence? -->")
-  Rel(user, system, "<!-- FILL: Primary interaction -->")
-\`\`\`
+    return `<!-- UNFILLED: C4 Context Diagram -->
+<!-- Run \`forgecraft generate_diagram\` to auto-generate from your spec -->
+# System Context Diagram
+\`\`\`mermaid
+C4Context
+  title System Context: ${projectName}
+  Person(user, "User", "<!-- FILL: Who uses the system? -->")
+  System(system, "${projectName}", "<!-- FILL: What does the system do in one sentence? -->")
+  Rel(user, system, "<!-- FILL: Primary interaction -->")
+\`\`\`
 `;
 }
 /**
@@ -51,32 +51,32 @@ C4Context
  * @returns Stub content with UNFILLED markers and structural Mermaid syntax
  */
 export function buildSequenceDiagramStub(feature) {
-    return `<!-- UNFILLED: Sequence Diagram — ${feature} -->
-<!-- Replace participant labels and messages with real actors and contracts -->
-# Sequence Diagram: ${feature}
-
-\`\`\`mermaid
-sequenceDiagram
-    participant Client as <!-- FILL: initiating actor, e.g. Browser / CLI / Service -->
-    participant API as <!-- FILL: entry-point service, e.g. API Gateway -->
-    participant Service as <!-- FILL: domain service, e.g. AuthService -->
-    participant Store as <!-- FILL: persistence layer, e.g. Database -->
-
-    Note over Client,Store: <!-- FILL: describe the primary flow in one sentence -->
-
-    Client->>API: <!-- FILL: request, e.g. POST /login {credentials} -->
-    API->>Service: <!-- FILL: delegate, e.g. authenticate(credentials) -->
-    Service->>Store: <!-- FILL: query, e.g. findUserByEmail(email) -->
-    Store-->>Service: <!-- FILL: result, e.g. User | null -->
-
-    alt <!-- FILL: failure case, e.g. User not found or wrong password -->
-        Service-->>API: <!-- FILL: error response, e.g. AuthError -->
-        API-->>Client: <!-- FILL: HTTP error, e.g. 401 Unauthorized -->
-    else <!-- FILL: success case -->
-        Service-->>API: <!-- FILL: success result, e.g. JWT token -->
-        API-->>Client: <!-- FILL: HTTP success, e.g. 200 OK {token} -->
-    end
-\`\`\`
+    return `<!-- UNFILLED: Sequence Diagram — ${feature} -->
+<!-- Replace participant labels and messages with real actors and contracts -->
+# Sequence Diagram: ${feature}
+
+\`\`\`mermaid
+sequenceDiagram
+    participant Client as <!-- FILL: initiating actor, e.g. Browser / CLI / Service -->
+    participant API as <!-- FILL: entry-point service, e.g. API Gateway -->
+    participant Service as <!-- FILL: domain service, e.g. AuthService -->
+    participant Store as <!-- FILL: persistence layer, e.g. Database -->
+
+    Note over Client,Store: <!-- FILL: describe the primary flow in one sentence -->
+
+    Client->>API: <!-- FILL: request, e.g. POST /login {credentials} -->
+    API->>Service: <!-- FILL: delegate, e.g. authenticate(credentials) -->
+    Service->>Store: <!-- FILL: query, e.g. findUserByEmail(email) -->
+    Store-->>Service: <!-- FILL: result, e.g. User | null -->
+
+    alt <!-- FILL: failure case, e.g. User not found or wrong password -->
+        Service-->>API: <!-- FILL: error response, e.g. AuthError -->
+        API-->>Client: <!-- FILL: HTTP error, e.g. 401 Unauthorized -->
+    else <!-- FILL: success case -->
+        Service-->>API: <!-- FILL: success result, e.g. JWT token -->
+        API-->>Client: <!-- FILL: HTTP success, e.g. 200 OK {token} -->
+    end
+\`\`\`
 `;
 }
 /**
@@ -90,30 +90,30 @@ sequenceDiagram
  * @returns Stub content with UNFILLED markers and structural Mermaid syntax
  */
 export function buildStateMachineDiagramStub(entityName) {
-    return `<!-- UNFILLED: State Machine — ${entityName} -->
-<!-- Replace state names (Draft, Pending, Active, etc.) and transition labels -->
-<!-- with the actual lifecycle states of your domain entity.               -->
-# State Machine: ${entityName}
-
-\`\`\`mermaid
-stateDiagram-v2
-    [*] --> Draft
-
-    Draft --> Pending: submit()
-    Pending --> Active: approve()
-    Pending --> Rejected: reject()
-    Active --> Completed: complete()
-    Active --> Cancelled: cancel()
-
-    Completed --> [*]
-    Rejected --> [*]
-    Cancelled --> [*]
-
-    note right of Active
-        FILL: add invariant or constraint
-        e.g. "requires valid payment method"
-    end note
-\`\`\`
+    return `<!-- UNFILLED: State Machine — ${entityName} -->
+<!-- Replace state names (Draft, Pending, Active, etc.) and transition labels -->
+<!-- with the actual lifecycle states of your domain entity.               -->
+# State Machine: ${entityName}
+
+\`\`\`mermaid
+stateDiagram-v2
+    [*] --> Draft
+
+    Draft --> Pending: submit()
+    Pending --> Active: approve()
+    Pending --> Rejected: reject()
+    Active --> Completed: complete()
+    Active --> Cancelled: cancel()
+
+    Completed --> [*]
+    Rejected --> [*]
+    Cancelled --> [*]
+
+    note right of Active
+        FILL: add invariant or constraint
+        e.g. "requires valid payment method"
+    end note
+\`\`\`
 `;
 }
 /**
@@ -126,29 +126,29 @@ stateDiagram-v2
  * @returns Stub content with UNFILLED markers and structural Mermaid syntax
  */
 export function buildFlowDiagramStub(ucName) {
-    return `<!-- UNFILLED: Flow Diagram — ${ucName} -->
-<!-- Replace node labels and edge conditions with real user journey steps -->
-# Flow: ${ucName}
-
-\`\`\`mermaid
-flowchart TD
-    Start([<!-- FILL: trigger, e.g. User opens registration page -->])
-
-    Start --> Input[<!-- FILL: first action, e.g. Fill in name, email, password -->]
-    Input --> Validate{<!-- FILL: validation check, e.g. All fields valid? -->}
-
-    Validate -->|<!-- FILL: failure label, e.g. Invalid -->| Error[<!-- FILL: error action, e.g. Show validation errors -->]
-    Error --> Input
-
-    Validate -->|<!-- FILL: success label, e.g. Valid -->| Process[<!-- FILL: main action, e.g. Create account -->]
-    Process --> Check{<!-- FILL: guard check, e.g. Email already exists? -->}
-
-    Check -->|<!-- FILL: conflict label, e.g. Yes -->| Conflict[<!-- FILL: conflict action, e.g. Show duplicate email error -->]
-    Conflict --> End([<!-- FILL: exit label, e.g. User corrects email -->])
-
-    Check -->|<!-- FILL: proceed label, e.g. No -->| Success[<!-- FILL: success action, e.g. Send confirmation email -->]
-    Success --> End
-\`\`\`
+    return `<!-- UNFILLED: Flow Diagram — ${ucName} -->
+<!-- Replace node labels and edge conditions with real user journey steps -->
+# Flow: ${ucName}
+
+\`\`\`mermaid
+flowchart TD
+    Start([<!-- FILL: trigger, e.g. User opens registration page -->])
+
+    Start --> Input[<!-- FILL: first action, e.g. Fill in name, email, password -->]
+    Input --> Validate{<!-- FILL: validation check, e.g. All fields valid? -->}
+
+    Validate -->|<!-- FILL: failure label, e.g. Invalid -->| Error[<!-- FILL: error action, e.g. Show validation errors -->]
+    Error --> Input
+
+    Validate -->|<!-- FILL: success label, e.g. Valid -->| Process[<!-- FILL: main action, e.g. Create account -->]
+    Process --> Check{<!-- FILL: guard check, e.g. Email already exists? -->}
+
+    Check -->|<!-- FILL: conflict label, e.g. Yes -->| Conflict[<!-- FILL: conflict action, e.g. Show duplicate email error -->]
+    Conflict --> End([<!-- FILL: exit label, e.g. User corrects email -->])
+
+    Check -->|<!-- FILL: proceed label, e.g. No -->| Success[<!-- FILL: success action, e.g. Send confirmation email -->]
+    Success --> End
+\`\`\`
 `;
 }
 /**
@@ -161,24 +161,24 @@ flowchart TD
  * @returns Stub content with UNFILLED markers and structural Mermaid syntax
  */
 export function buildC4ContainerStub(projectName) {
-    return `<!-- UNFILLED: C4 Container Diagram -->
-<!-- Replace container labels, technology fields, and relations with your stack -->
-# Container Diagram — ${projectName}
-
-\`\`\`mermaid
-C4Container
-    title Container Diagram: ${projectName}
-
-    Person(user, "<!-- FILL: actor name -->", "<!-- FILL: actor description -->")
-
-    Container(web, "<!-- FILL: frontend name, e.g. Web Application -->", "<!-- FILL: technology, e.g. React -->", "<!-- FILL: responsibility -->")
-    Container(api, "<!-- FILL: backend name, e.g. API Server -->", "<!-- FILL: technology, e.g. Node.js / Express -->", "<!-- FILL: responsibility -->")
-    Container(db, "<!-- FILL: database name, e.g. Primary Database -->", "<!-- FILL: technology, e.g. PostgreSQL -->", "<!-- FILL: responsibility -->")
-
-    Rel(user, web, "<!-- FILL: interaction, e.g. Uses -->", "<!-- FILL: protocol, e.g. HTTPS -->")
-    Rel(web, api, "<!-- FILL: call, e.g. API calls -->", "<!-- FILL: protocol, e.g. REST / JSON -->")
-    Rel(api, db, "<!-- FILL: query, e.g. Reads and writes -->", "<!-- FILL: protocol, e.g. SQL -->")
-\`\`\`
+    return `<!-- UNFILLED: C4 Container Diagram -->
+<!-- Replace container labels, technology fields, and relations with your stack -->
+# Container Diagram — ${projectName}
+
+\`\`\`mermaid
+C4Container
+    title Container Diagram: ${projectName}
+
+    Person(user, "<!-- FILL: actor name -->", "<!-- FILL: actor description -->")
+
+    Container(web, "<!-- FILL: frontend name, e.g. Web Application -->", "<!-- FILL: technology, e.g. React -->", "<!-- FILL: responsibility -->")
+    Container(api, "<!-- FILL: backend name, e.g. API Server -->", "<!-- FILL: technology, e.g. Node.js / Express -->", "<!-- FILL: responsibility -->")
+    Container(db, "<!-- FILL: database name, e.g. Primary Database -->", "<!-- FILL: technology, e.g. PostgreSQL -->", "<!-- FILL: responsibility -->")
+
+    Rel(user, web, "<!-- FILL: interaction, e.g. Uses -->", "<!-- FILL: protocol, e.g. HTTPS -->")
+    Rel(web, api, "<!-- FILL: call, e.g. API calls -->", "<!-- FILL: protocol, e.g. REST / JSON -->")
+    Rel(api, db, "<!-- FILL: query, e.g. Reads and writes -->", "<!-- FILL: protocol, e.g. SQL -->")
+\`\`\`
 `;
 }
 /**

package/dist/tools/scaffold-templates.js

@@ -1,76 +1,76 @@
 /**
  * scaffold-templates: Static template strings and render functions for scaffold_project.
  */
-export const PROJECT_SPECIFIC_TEMPLATE = `# Project-Specific Rules
-<!-- This file is owned by YOU. ForgeCraft will never overwrite it. -->
-<!-- Add project-specific rules, framework choices, conventions, and corrections here. -->
-<!-- The sentinel CLAUDE.md links here so any AI reading your project can find it. -->
-
-## Framework & Stack Choices
-<!-- e.g. We use Prisma for ORM. Deploy target is Railway. Python 3.11+. -->
-
-## Custom Corrections Log
-<!-- Log AI corrections so the pattern isn't repeated. -->
-<!-- Format: - YYYY-MM-DD: [description of correction] -->
-
-## Project-Specific Gates
-<!-- Add quality rules specific to this project that don't belong in universal standards. -->
+export const PROJECT_SPECIFIC_TEMPLATE = `# Project-Specific Rules
+<!-- This file is owned by YOU. ForgeCraft will never overwrite it. -->
+<!-- Add project-specific rules, framework choices, conventions, and corrections here. -->
+<!-- The sentinel CLAUDE.md links here so any AI reading your project can find it. -->
+
+## Framework & Stack Choices
+<!-- e.g. We use Prisma for ORM. Deploy target is Railway. Python 3.11+. -->
+
+## Custom Corrections Log
+<!-- Log AI corrections so the pattern isn't repeated. -->
+<!-- Format: - YYYY-MM-DD: [description of correction] -->
+
+## Project-Specific Gates
+<!-- Add quality rules specific to this project that don't belong in universal standards. -->
 `;
 export const EXCEPTIONS_TEMPLATE = JSON.stringify({
     version: "1",
     _comment: "Hook false-positive exceptions. Add entries here to prevent rediscovering the same false positive each session. Each entry: {id, hook, pattern, reason, addedAt, addedBy, adr?}",
     exceptions: [],
 }, null, 2) + "\n";
-export const PROJECT_GATES_TEMPLATE = `version: "1"
-# Project-specific quality gates.
-# Gates you discover while working that should be enforced for this project.
-# Set generalizable: true + fill in evidence to contribute to the community registry.
-# See: https://github.com/jghiringhelli/quality-gates/issues/new?template=quality-gate-proposal.md
-gates: []
+export const PROJECT_GATES_TEMPLATE = `version: "1"
+# Project-specific quality gates.
+# Gates you discover while working that should be enforced for this project.
+# Set generalizable: true + fill in evidence to contribute to the community registry.
+# See: https://github.com/jghiringhelli/quality-gates/issues/new?template=quality-gate-proposal.md
+gates: []
 `;
-export const SMOKE_TESTS_README = `# Smoke Tests
-
-Generated by ForgeCraft scaffold. Fill in the critical paths from your tech spec.
-
-## What smoke tests cover
-- Every API entry point that serves real users
-- Every critical user journey end-to-end
-- Every DB migration (verify schema applied correctly)
-- Every external integration handshake
-
-## Format
-Use the tool configured in forgecraft.yaml deployment.testing.smokeTool (or default to HTTP assertions).
-All smoke tests must complete in < 60 seconds total.
-
-## Running
-See forgecraft.yaml tools.test or your project's test runner.
-Results are written to .forgecraft/reports/smoke-latest.json.
-
-## Required before deployment
-All smoke tests must pass against staging before any production deploy.
-See verification.yaml deployment-gates phase.
+export const SMOKE_TESTS_README = `# Smoke Tests
+
+Generated by ForgeCraft scaffold. Fill in the critical paths from your tech spec.
+
+## What smoke tests cover
+- Every API entry point that serves real users
+- Every critical user journey end-to-end
+- Every DB migration (verify schema applied correctly)
+- Every external integration handshake
+
+## Format
+Use the tool configured in forgecraft.yaml deployment.testing.smokeTool (or default to HTTP assertions).
+All smoke tests must complete in < 60 seconds total.
+
+## Running
+See forgecraft.yaml tools.test or your project's test runner.
+Results are written to .forgecraft/reports/smoke-latest.json.
+
+## Required before deployment
+All smoke tests must pass against staging before any production deploy.
+See verification.yaml deployment-gates phase.
 `;
-export const LOAD_TESTS_README = `# Load Tests
-
-Generated by ForgeCraft scaffold. Fill in the parameters from your tech spec.
-
-## Parameters (fill in from forgecraft.yaml deployment.testing.load)
-- Concurrent users: [TODO: concurrentUsers from forgecraft.yaml]
-- Target RPS: [TODO: targetRps from forgecraft.yaml]
-- p99 ceiling: [TODO: p99CeilingMs ms]
-- Duration: [TODO: durationSeconds seconds minimum]
-
-## When these parameters are missing
-Deploying without stated load test parameters is full deployment with manual monitoring.
-The paper requires: parameters named in spec BEFORE the test runs, not after.
-Add them to forgecraft.yaml deployment.testing.load before running.
-
-## Tool
-Use the tool configured in forgecraft.yaml deployment.testing.load.tool (k6, Artillery, Locust, etc.)
-Results are written to .forgecraft/reports/load-latest.json.
-
-## Required before pre-release
-See verification.yaml pre-release-hardening phase, load-test step.
+export const LOAD_TESTS_README = `# Load Tests
+
+Generated by ForgeCraft scaffold. Fill in the parameters from your tech spec.
+
+## Parameters (fill in from forgecraft.yaml deployment.testing.load)
+- Concurrent users: [TODO: concurrentUsers from forgecraft.yaml]
+- Target RPS: [TODO: targetRps from forgecraft.yaml]
+- p99 ceiling: [TODO: p99CeilingMs ms]
+- Duration: [TODO: durationSeconds seconds minimum]
+
+## When these parameters are missing
+Deploying without stated load test parameters is full deployment with manual monitoring.
+The paper requires: parameters named in spec BEFORE the test runs, not after.
+Add them to forgecraft.yaml deployment.testing.load before running.
+
+## Tool
+Use the tool configured in forgecraft.yaml deployment.testing.load.tool (k6, Artillery, Locust, etc.)
+Results are written to .forgecraft/reports/load-latest.json.
+
+## Required before pre-release
+See verification.yaml pre-release-hardening phase, load-test step.
 `;
 /**
  * Render the bootstrap README for docs/adrs/.

package/dist/tools/setup-artifact-writers.d.ts

@@ -3,6 +3,23 @@
  */
 import type { CascadeDecision } from "../shared/types.js";
 import { deriveDefaultCascadeDecisions } from "./cascade-defaults.js";
+/**
+ * Result of a pre-flight git environment check.
+ *
+ * - `repo`    — a `.git` directory exists; all good.
+ * - `no-repo` — git is installed but no repository exists yet; ForgeCraft will init one.
+ * - `no-git`  — git binary not found; user must install git before setup can proceed.
+ */
+export type GitStatus = "repo" | "no-repo" | "no-git";
+/**
+ * Check whether a git repository and the git binary are present.
+ *
+ * Does NOT modify the filesystem. Safe to call at any time.
+ *
+ * @param projectDir - Absolute path to the project root
+ * @returns Current git status for the directory
+ */
+export declare function checkGitStatus(projectDir: string): GitStatus;
 /**
  * Initialise a git repository in projectDir if one does not already exist.
  * Falls back gracefully when git is not installed.
@@ -60,6 +77,19 @@ export declare function writePrd(projectDir: string, projectName: string, aiFiel
  */
 export declare function writeUseCases(projectDir: string, projectName: string, aiFields: AiExtractedFields, _specContent: string | null): boolean;
 export { deriveDefaultCascadeDecisions };
+/**
+ * Write docs/sample-outcome.md — a stub for the first real deliverable of
+ * a generative tool. Created when Phase 2 receives tool_sample_split = "tool_and_sample".
+ *
+ * The AI assistant should fill in the sections from the creative content
+ * described in the spec (the book, song, game, artwork, etc.).
+ * Never overwrites an existing file.
+ *
+ * @param projectDir - Project root
+ * @param toolName - Name of the core generative tool
+ * @returns True if the file was written
+ */
+export declare function writeSampleOutcome(projectDir: string, toolName: string): boolean;
 /**
  * Load cascade decisions from forgecraft.yaml (convenience re-used in writers).
  */

package/dist/tools/setup-artifact-writers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-artifact-writers.d.ts","sourceRoot":"","sources":["../../src/tools/setup-artifact-writers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,6BAA6B,EAAE,MAAM,uBAAuB,CAAC;AAItE;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAwBtD;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,eAAe,EAAE,EAC5B,aAAa,CAAC,EAAE,OAAO,EACvB,UAAU,CAAC,EAAE,OAAO,GACnB,OAAO,CAkBT;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAcpE;AAID,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,OAAO,CAMT;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,OAAO,CAMT;AAgBD,OAAO,EAAE,6BAA6B,EAAE,CAAC;AAEzC;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,EAAE,GAAG,IAAI,CAUzF"}
+{"version":3,"file":"setup-artifact-writers.d.ts","sourceRoot":"","sources":["../../src/tools/setup-artifact-writers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,6BAA6B,EAAE,MAAM,uBAAuB,CAAC;AAItE;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAQ5D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAwBtD;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,eAAe,EAAE,EAC5B,aAAa,CAAC,EAAE,OAAO,EACvB,UAAU,CAAC,EAAE,OAAO,GACnB,OAAO,CA8BT;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAwBpE;AAID,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,OAAO,CAMT;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,OAAO,CAUT;AAuDD,OAAO,EAAE,6BAA6B,EAAE,CAAC;AAIzC;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CA4CT;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,GACjB,eAAe,EAAE,GAAG,IAAI,CAY1B"}

package/dist/tools/setup-artifact-writers.js

@@ -1,12 +1,30 @@
 /**
  * setup-artifact-writers: Writers for forgecraft.yaml, PRD, use-cases, and git init.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { execSync } from "node:child_process";
 import yaml from "js-yaml";
 import { deriveDefaultCascadeDecisions } from "./cascade-defaults.js";
-// ── Git initialization ────────────────────────────────────────────────
+/**
+ * Check whether a git repository and the git binary are present.
+ *
+ * Does NOT modify the filesystem. Safe to call at any time.
+ *
+ * @param projectDir - Absolute path to the project root
+ * @returns Current git status for the directory
+ */
+export function checkGitStatus(projectDir) {
+    if (existsSync(join(projectDir, ".git")))
+        return "repo";
+    try {
+        execSync("git --version", { stdio: "ignore" });
+        return "no-repo";
+    }
+    catch {
+        return "no-git";
+    }
+}
 /**
  * Initialise a git repository in projectDir if one does not already exist.
  * Falls back gracefully when git is not installed.
@@ -127,7 +145,12 @@ export function writePrd(projectDir, projectName, aiFields, _specContent) {
 }
 function buildPrdContent(projectName, aiFields) {
     const fill = (placeholder) => `<!-- FILL: ${placeholder} -->`;
-    const listOrFill = (csv, placeholder) => csv ? csv.split(",").map((s) => `- ${s.trim()}`).join("\n") : fill(placeholder);
+    const listOrFill = (csv, placeholder) => csv
+        ? csv
+            .split(",")
+            .map((s) => `- ${s.trim()}`)
+            .join("\n")
+        : fill(placeholder);
     return [
         `# ${projectName}\n`,
         `## Problem\n\n${aiFields.problemStatement ?? fill("describe the problem this project solves")}\n`,
@@ -157,18 +180,107 @@ export function writeUseCases(projectDir, projectName, aiFields, _specContent) {
 }
 function buildUseCasesContent(projectName, aiFields) {
     const fill = (placeholder) => `<!-- FILL: ${placeholder} -->`;
-    const actors = aiFields.primaryUsers ? aiFields.primaryUsers.split(",").map((s) => s.trim()) : [];
+    const actors = aiFields.primaryUsers
+        ? aiFields.primaryUsers.split(",").map((s) => s.trim())
+        : [];
     const primaryActor = actors[0] ?? fill("primary actor");
     const secondaryActor = actors[1] ?? actors[0] ?? fill("secondary actor");
     const thirdActor = actors[2] ?? actors[0] ?? fill("actor");
-    const problemContext = aiFields.problemStatement ? aiFields.problemStatement.slice(0, 150).replace(/\n/g, " ") : fill("problem context");
-    const uc1 = [`## UC-001: Accomplish Primary Goal`, ``, `**Actor**: ${primaryActor}`, `**Precondition**: Actor is authenticated and the system is operational.`, `**Steps**:`, `1. Actor initiates the primary workflow.`, `2. System validates the request and processes the input.`, `3. System returns the result confirming the action was completed.`, `**Outcome**: The actor's goal is achieved. Context: ${problemContext}`].join("\n");
-    const uc2 = [`## UC-002: Configure and Manage`, ``, `**Actor**: ${secondaryActor}`, `**Precondition**: Actor has appropriate permissions.`, `**Steps**:`, `1. Actor selects the configuration option.`, `2. System presents available options and current state.`, `3. Actor applies changes; system persists the configuration.`, `**Outcome**: Configuration is updated and takes effect immediately.`].join("\n");
-    const uc3 = [`## UC-003: Review and Observe`, ``, `**Actor**: ${thirdActor}`, `**Precondition**: At least one operation has been completed.`, `**Steps**:`, `1. Actor navigates to the overview section.`, `2. System retrieves and displays the current state and history.`, `3. Actor reviews the information and takes appropriate action.`, `**Outcome**: Actor has a clear picture of the current system state.`].join("\n");
+    const problemContext = aiFields.problemStatement
+        ? aiFields.problemStatement.slice(0, 150).replace(/\n/g, " ")
+        : fill("problem context");
+    const uc1 = [
+        `## UC-001: Accomplish Primary Goal`,
+        ``,
+        `**Actor**: ${primaryActor}`,
+        `**Precondition**: Actor is authenticated and the system is operational.`,
+        `**Steps**:`,
+        `1. Actor initiates the primary workflow.`,
+        `2. System validates the request and processes the input.`,
+        `3. System returns the result confirming the action was completed.`,
+        `**Outcome**: The actor's goal is achieved. Context: ${problemContext}`,
+    ].join("\n");
+    const uc2 = [
+        `## UC-002: Configure and Manage`,
+        ``,
+        `**Actor**: ${secondaryActor}`,
+        `**Precondition**: Actor has appropriate permissions.`,
+        `**Steps**:`,
+        `1. Actor selects the configuration option.`,
+        `2. System presents available options and current state.`,
+        `3. Actor applies changes; system persists the configuration.`,
+        `**Outcome**: Configuration is updated and takes effect immediately.`,
+    ].join("\n");
+    const uc3 = [
+        `## UC-003: Review and Observe`,
+        ``,
+        `**Actor**: ${thirdActor}`,
+        `**Precondition**: At least one operation has been completed.`,
+        `**Steps**:`,
+        `1. Actor navigates to the overview section.`,
+        `2. System retrieves and displays the current state and history.`,
+        `3. Actor reviews the information and takes appropriate action.`,
+        `**Outcome**: Actor has a clear picture of the current system state.`,
+    ].join("\n");
     return [`# Use Cases — ${projectName}`, ``, uc1, ``, uc2, ``, uc3, ``].join("\n");
 }
 // ── Re-export deriveDefaultCascadeDecisions for convenience ──────────
 export { deriveDefaultCascadeDecisions };
+// ── Sample-outcome writer ─────────────────────────────────────────────
+/**
+ * Write docs/sample-outcome.md — a stub for the first real deliverable of
+ * a generative tool. Created when Phase 2 receives tool_sample_split = "tool_and_sample".
+ *
+ * The AI assistant should fill in the sections from the creative content
+ * described in the spec (the book, song, game, artwork, etc.).
+ * Never overwrites an existing file.
+ *
+ * @param projectDir - Project root
+ * @param toolName - Name of the core generative tool
+ * @returns True if the file was written
+ */
+export function writeSampleOutcome(projectDir, toolName) {
+    const outcomePath = join(projectDir, "docs", "sample-outcome.md");
+    if (existsSync(outcomePath))
+        return false;
+    mkdirSync(join(projectDir, "docs"), { recursive: true });
+    const fill = (placeholder) => `<!-- FILL: ${placeholder} -->`;
+    const content = [
+        `# Sample Outcome — First Real Deliverable`,
+        ``,
+        `> **What this file is:** The core tool is **${toolName}**. This file captures the`,
+        `> first specific creative work the tool will produce — the proof that the tool works.`,
+        `> It is an acceptance test, not a deliverable in itself.`,
+        `> Read the original spec and extract the creative content details into the sections below.`,
+        ``,
+        `## The Work`,
+        ``,
+        `**Title / Name**: ${fill("name of the book, song, game, artwork, etc.")}`,
+        `**Type**: ${fill("novel | music track | game | artwork | script | other")}`,
+        ``,
+        `## Description`,
+        ``,
+        fill("brief description of what this creative work is — 2-3 sentences from the spec"),
+        ``,
+        `## Key Elements`,
+        ``,
+        fill("characters, themes, setting, style, structure — the specifics from the spec"),
+        ``,
+        `## Acceptance Criteria`,
+        ``,
+        `The tool has succeeded with this first outcome when:`,
+        ``,
+        `- [ ] ${fill("first measurable criterion — e.g. 'generates a coherent chapter 1'")}`,
+        `- [ ] ${fill("second criterion")}`,
+        `- [ ] ${fill("third criterion")}`,
+        ``,
+        `## Notes`,
+        ``,
+        fill("anything else from the spec about this specific creative work"),
+    ].join("\n");
+    writeFileSync(outcomePath, content, "utf-8");
+    return true;
+}
 /**
  * Load cascade decisions from forgecraft.yaml (convenience re-used in writers).
  */