@warpgogol/forge 2.17.0 → 2.20.0

package/README.md

@@ -46,6 +46,7 @@ For full project lifecycle management — missions, releases, deployment, certif
 | [`@warpgogol/werkstatt-phaser-game`](https://github.com/syrokomskyi/werkstatt-phaser-game) | Phaser game plugin — phaser validators, Vite build, deploy adapters | Browser game projects (`phaser-turborepo`) |
 | [`@warpgogol/werkstatt-godot-game`](https://github.com/syrokomskyi/werkstatt-godot-game) | Godot plugin — scene validators, dotnet build, itch.io deploy, Godot skills | Godot game projects (`godot-csharp`) |
 | [`@warpgogol/werkstatt-knowledge`](https://github.com/syrokomskyi/werkstatt-knowledge) | Knowledge plugin — source binding, canonical verification, extraction, materialization, release checks | Knowledge system projects (`knowledge-typescript-turborepo`) |
+| [`@warpgogol/werkstatt-typescript`](https://github.com/syrokomskyi/werkstatt) | TypeScript plugin — tsconfig, import boundaries, phantom deps, package exports, strict mode, barrel validators | TypeScript TurboRepo projects (`typescript-turborepo`) |
 
 ### When you need these packages
 
@@ -65,6 +66,11 @@ pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-godot-game
 pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-knowledge
 ```
 
+```sh
+# TypeScript TurboRepo project
+pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-typescript
+```
+
 > **Note for agents:** When scaffolding a new project with `forge create`, always install the engine and matching stack plugin after the scaffold completes. The `forge.yaml` bindings reference commands from these packages (e.g. `pnpm exec werkstatt run rfc.validate`), and they will fail if the packages are not installed.
 
 ---
@@ -217,6 +223,7 @@ You need to run one command in the terminal to create your project. After that,
    | Browser game (2D, arcade, puzzle)   | `--profile phaser-turborepo`               |
    | Godot game (desktop, mobile, 2D/3D) | `--profile godot-csharp`                   |
    | Knowledge system (evidence-backed)  | `--profile knowledge-typescript-turborepo` |
+   | TypeScript library (monorepo)       | `--profile typescript-turborepo`           |
    | Library or governance-only project  | `--profile forge-shell`                    |
 
 2. **Open the project folder in your AI IDE.** Open the folder from step 1 in Windsurf or your preferred IDE.
@@ -297,6 +304,9 @@ pnpm dlx @warpgogol/forge@latest create --in-place --profile godot-csharp
 mkdir my-knowledge-base && cd my-knowledge-base
 pnpm dlx @warpgogol/forge@latest create --in-place --profile knowledge-typescript-turborepo
 
+mkdir my-ts-project && cd my-ts-project
+pnpm dlx @warpgogol/forge@latest create --in-place --profile typescript-turborepo
+
 # Override the project name (derived from folder name by default)
 pnpm dlx @warpgogol/forge@latest create --in-place --profile forge-shell --name my-custom-name
 ```
@@ -346,6 +356,7 @@ A stack profile defines the project scaffold: directory structure, dependencies,
 | `phaser-turborepo` | Browser game | Phaser + TypeScript + pnpm + Turborepo | `games/my-game` | Browser games, interactive experiences |
 | `godot-csharp` | Godot game | Godot 4.x + C# + pnpm + Turborepo | `games/my-game` | Desktop/mobile games, Godot-based interactive projects |
 | `knowledge-typescript-turborepo` | Knowledge system | TypeScript + pnpm + Turborepo | `knowledge/my-kb` | Evidence-backed knowledge bases, structured datasets with source provenance |
+| `typescript-turborepo` | TypeScript library | TypeScript + pnpm + Turborepo | — | Generic TypeScript TurboRepo monorepo with best-practice validators |
 
 ```sh
 # List available profiles (after install)

package/os/core/core.module.ts

@@ -296,7 +296,7 @@ export const forgeCoreModule: ForgeModule = {
           kind: "string",
           required: true,
           description:
-            "Stack profile id. Required. Available: forge-shell, phaser-turborepo, godot-csharp.",
+            "Stack profile id. Required. Available: forge-shell, phaser-turborepo, godot-csharp, knowledge-typescript-turborepo, typescript-turborepo.",
         },
         name: {
           kind: "string",

package/os/spec/live-spec-merge.test.ts

@@ -157,6 +157,50 @@ nonGoals: []
 Content.
 `;
 
+const SAMPLE_RFC_9004 = `---
+id: RFC-9004
+title: "Second RFC with same headings"
+status: implemented
+kind: architecture
+scope: workspace
+owners:
+  - architecture
+reviewers:
+  - human:test
+createdAt: 2026-08-06
+updatedAt: 2026-08-06
+implementedAt: 2026-08-06
+versionBump: patch
+liveSpec: true
+packagesImpacted:
+  - packages/forge
+commands:
+  proposed: []
+  added: []
+  changed: []
+  removed: []
+appsImpacted: []
+successSignals: []
+nonGoals: []
+---
+
+# RFC-9004: Second RFC with same headings
+
+## Design
+
+### CLI surface
+
+Different CLI content from RFC-9004.
+
+### TypeScript contracts
+
+Different types from RFC-9004.
+
+## Rollout
+
+Some rollout.
+`;
+
 async function setupWorkspace(): Promise<string> {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "spec-live-test-"));
   const rfcDir = path.join(tmpDir, "docs/rfcs");
@@ -164,6 +208,7 @@ async function setupWorkspace(): Promise<string> {
   await fs.writeFile(path.join(rfcDir, "rfc-9001-test-rfc-for-living-specs.md"), SAMPLE_RFC);
   await fs.writeFile(path.join(rfcDir, "rfc-9002-test-rfc-without-livespec.md"), SAMPLE_RFC_NO_LIVE_SPEC);
   await fs.writeFile(path.join(rfcDir, "rfc-9003-rejected-rfc-with-livespec.md"), SAMPLE_RFC_REJECTED);
+  await fs.writeFile(path.join(rfcDir, "rfc-9004-second-rfc-with-same-headings.md"), SAMPLE_RFC_9004);
   return tmpDir;
 }
 
@@ -258,4 +303,35 @@ describe("spec.live.merge", () => {
     expect(result.exitCode).toBe(1);
     expect(result.summary).toContain("not found");
   });
+
+  it("namespaces headings by RFC ID and allows multiple RFCs with same heading names", async () => {
+    // First merge creates the spec with RFC-9001 headings
+    const input1: ForgeCommandInput = { argv: [], flags: { id: "RFC-9001" } };
+    await runSpecLiveMerge(input1, makeContext(tmpDir));
+
+    // Second merge with RFC-9004 (same heading names) should NOT conflict
+    const input2: ForgeCommandInput = { argv: [], flags: { id: "RFC-9004" } };
+    const result = await runSpecLiveMerge(input2, makeContext(tmpDir));
+
+    expect(result.exitCode).toBe(0);
+    expect(result.data?.conflicts.length).toBe(0);
+    expect(result.data?.deltas.length).toBeGreaterThan(0);
+
+    const specFile = path.join(tmpDir, "docs/specs/live/forge.md");
+    const content = await fs.readFile(specFile, "utf-8");
+    expect(content).toContain("CLI surface (RFC-9001)");
+    expect(content).toContain("CLI surface (RFC-9004)");
+  });
+
+  it("re-merges namespaced headings without conflicts on subsequent docs.archive runs", async () => {
+    // Initial merges
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9001" } }, makeContext(tmpDir));
+    await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9004" } }, makeContext(tmpDir));
+
+    // Re-merge RFC-9001 (simulates docs.archive re-running all merges)
+    const result = await runSpecLiveMerge({ argv: [], flags: { id: "RFC-9001" } }, makeContext(tmpDir));
+
+    expect(result.exitCode).toBe(0);
+    expect(result.data?.conflicts.length).toBe(0);
+  });
 });

package/os/spec/live-spec-merge.ts

@@ -1,15 +1,16 @@
 /*
 <MODULE_CONTRACT>
 <purpose>spec.live.merge handler — extracts deltas from an RFC's ## Design section,
-classifies them as ADDED/MODIFIED/REMOVED, applies to a living spec, handles conflicts
-with all-or-nothing semantics, and writes atomically (RFC-0711).</purpose>
+classifies them as ADDED/MODIFIED/REMOVED, applies to a living spec with RFC-namespaced
+headings, and writes atomically (RFC-0711).</purpose>
 <non-goals>
   <item>Do not handle docs.archive integration — that is in core.module.ts.</item>
   <item>Do not validate living specs — that is spec.live.validate.</item>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0711: initial spec.live.merge handler with delta extraction, classification, conflict detection, and atomic writes.</item>
+  <item>RFC-0711: initial spec.live.merge handler with delta extraction, classification, and atomic writes.</item>
+  <item>RFC-0957: namespace headings by RFC ID, remove conflict detection (structurally impossible with namespacing).</item>
 </CHANGE_SUMMARY>
 */
 
@@ -29,7 +30,6 @@ import type {
   LivingSpec,
   LivingSpecHistoryEntry,
   DeltaOperation,
-  DeltaConflict,
   SpecLiveMergeResult,
 } from "./live-spec-types.ts";
 
@@ -162,6 +162,13 @@ function escapeRegex(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+function namespaceHeadings(content: string, rfcId: string): string {
+  return content.replace(/^(#{3,})\s+(.+)$/gm, (_match, hashes: string, text: string) => {
+    if (/\(RFC-\d{4}\)$/.test(text)) return `${hashes} ${text}`;
+    return `${hashes} ${text} (${rfcId})`;
+  });
+}
+
 function findRfcFile(rfcDir: string, rfcId: string): Promise<string | null> {
   return (async () => {
     const files = await listRfcFiles(rfcDir);
@@ -252,8 +259,8 @@ export async function runSpecLiveMerge(
     };
   }
 
-  const designSection = extractDesignSection(parsed.body);
-  if (!designSection) {
+  const rawDesignSection = extractDesignSection(parsed.body);
+  if (!rawDesignSection) {
     return {
       data: {
         command: "spec.live.merge",
@@ -268,6 +275,7 @@ export async function runSpecLiveMerge(
     };
   }
 
+  const designSection = namespaceHeadings(rawDesignSection, rfcId);
   const rfcHeadings = parseHeadings(designSection);
   const liveSpecsDir = path.join(workspaceRoot, LIVE_SPECS_DIR);
   const specFilePath = path.join(liveSpecsDir, `${domain}.md`);
@@ -279,7 +287,6 @@ export async function runSpecLiveMerge(
   }
 
   const operations: DeltaOperation[] = [];
-  const conflicts: DeltaConflict[] = [];
   const today = new Date().toISOString().slice(0, 10);
 
   if (!existingSpec) {
@@ -329,54 +336,12 @@ export async function runSpecLiveMerge(
   for (const heading of rfcHeadings) {
     const existing = findHeadingInSpec(existingSpec, heading.text);
     if (existing) {
-      let lastRfc: string | undefined;
-      for (let i = existingSpec.history.length - 1; i >= 0; i--) {
-        const entry = existingSpec.history[i]!;
-        if (entry.operation !== "removed") {
-          lastRfc = entry.rfc;
-          break;
-        }
-      }
-      if (lastRfc && lastRfc !== rfcId) {
-        conflicts.push({
-          heading: heading.text,
-          existingRfc: lastRfc,
-          newRfc: rfcId,
-          resolution: "pending",
-        });
-      }
       operations.push({ type: "modified", heading: heading.text, rfc: rfcId });
     } else {
       operations.push({ type: "added", heading: heading.text, rfc: rfcId });
     }
   }
 
-  if (conflicts.length > 0) {
-    const result: SpecLiveMergeResult = {
-      command: "spec.live.merge",
-      domain,
-      operation: "modified",
-      deltas: operations,
-      conflicts,
-      dryRun,
-    };
-
-    if (outputFormat === "pretty") {
-      logger.error(
-        `spec.live.merge: ${conflicts.length} conflict(s) detected — merge aborted (all-or-nothing)`,
-      );
-      for (const c of conflicts) {
-        logger.error(`  conflict: heading "${c.heading}" last modified by ${c.existingRfc}, now ${c.newRfc}`);
-      }
-    }
-
-    return {
-      data: result,
-      exitCode: 1,
-      summary: `spec.live.merge: ${conflicts.length} conflict(s) — merge aborted`,
-    };
-  }
-
   const updatedBody = applyDeltasToSpecBody(existingSpec.body, rfcHeadings, operations);
 
   const updatedSpec: LivingSpec = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "2.17.0",
+  "version": "2.20.0",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/profiles/godot-csharp.yaml

@@ -81,7 +81,7 @@ prerequisites:
 workspaceTypes:
   - id: game
     detect:
-      glob: "project.godot"
+      glob: project.godot
     skills:
       - godot-feature
       - godot-scene-review
@@ -93,13 +93,13 @@ invariants:
     check:
       kind: filename-pattern
       glob: "**/*.tscn"
-      pattern: "^Scenes/"
+      pattern: ^Scenes/
   - id: GODOT-02
     rule: The .godot/ directory must not be committed to git
     severity: error
     check:
       kind: gitignore-entry
-      pattern: ".godot/"
+      pattern: .godot/
   - id: GODOT-03
     rule: No hardcoded API keys or secrets in C# source files
     severity: error
@@ -111,7 +111,7 @@ invariants:
     severity: warning
     check:
       kind: file-contains
-      glob: "project.godot"
+      glob: project.godot
       pattern: ""
 workspace:
   dirs:

package/profiles/typescript-turborepo.yaml

@@ -0,0 +1,222 @@
+schema: forge/stack-profile@1
+id: typescript-turborepo
+displayName: TypeScript TurboRepo
+detect:
+  anyOf:
+    - tsconfig.base.json
+workspace:
+  dirs:
+    - docs
+    - scripts
+    - tools
+    - packages
+  files:
+    - path: .vscode/extensions.json
+      content: |
+        {
+          "recommendations": [
+            "dbaeumer.vscode-eslint",
+            "esbenp.prettier-vscode",
+            "github.vscode-github-actions",
+            "mechatroner.rainbow-csv"
+          ]
+        }
+    - path: .gitignore
+      content: |
+        node_modules
+        dist
+        .turbo
+        .cache
+        operator-profile.md
+    - path: package.json
+      content: |
+        {
+          "name": "__PROJECT_NAME__",
+          "version": "0.1.0",
+          "private": true,
+          "type": "module",
+          "engines": {
+            "node": ">=24 <25"
+          },
+          "scripts": {
+            "clean": "node scripts/clean.mjs",
+            "format": "prettier --write .",
+            "format:check": "prettier --check .",
+            "test": "vitest run --passWithNoTests",
+            "upgrade-packages": "pnpm up"
+          }
+        }
+    - path: pnpm-workspace.yaml
+      content: |
+        packages:
+          - packages/*
+    - path: scripts/clean.mjs
+      content: |
+        import { readdir, rm } from "node:fs/promises";
+        import { join } from "node:path";
+        import { fileURLToPath } from "node:url";
+
+        const TARGETS = new Set(["node_modules", ".turbo", "dist", ".cache"]);
+
+        const repoRoot = join(fileURLToPath(import.meta.url), "..", "..");
+
+        async function walk(dir, toDelete) {
+          const entries = await readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            const name = entry.name;
+            const fullPath = join(dir, name);
+            if (TARGETS.has(name)) {
+              toDelete.push(fullPath);
+              continue;
+            }
+            await walk(fullPath, toDelete);
+          }
+        }
+
+        const toDelete = [];
+        await walk(repoRoot, toDelete);
+
+        if (toDelete.length === 0) {
+          console.log("Nothing to clean.");
+          process.exit(0);
+        }
+
+        await Promise.all(toDelete.map((p) => rm(p, { recursive: true, force: true })));
+
+        for (const p of toDelete) {
+          console.log("deleted", p.replace(repoRoot + "/", ""));
+        }
+
+        console.log(`Cleaned ${toDelete.length} directories.`)
+    - path: turbo.json
+      content: |
+        {
+          "$schema": "https://turbo.build/schema.json",
+          "tasks": {
+            "build:check": {},
+            "test": {},
+            "lint": {}
+          }
+        }
+    - path: tsconfig.base.json
+      content: |
+        {
+          "compilerOptions": {
+            "target": "ES2022",
+            "module": "preserve",
+            "moduleResolution": "Bundler",
+            "strict": true,
+            "esModuleInterop": true,
+            "skipLibCheck": true,
+            "isolatedModules": true,
+            "forceConsistentCasingInFileNames": true,
+            "resolveJsonModule": true,
+            "noEmit": true,
+            "allowImportingTsExtensions": true,
+            "declaration": true,
+            "rewriteRelativeImportExtensions": true,
+            "types": ["node"]
+          }
+        }
+    - path: .npmrc
+      content: |
+        # @warpgogol scoped registry — replace YOUR_NPM_TOKEN with a valid npm read token
+        @warpgogol:registry=https://registry.npmjs.org/
+        //registry.npmjs.org/:_authToken=YOUR_NPM_TOKEN
+        dangerously-allow-all-builds=true
+    - path: eslint.config.js
+      content: |
+        export default [
+          {
+            rules: {},
+          },
+        ];
+    - path: .prettierrc.mjs
+      content: |
+        export default {
+          "semi": true,
+          "singleQuote": false,
+          "trailingComma": "all",
+          "printWidth": 100,
+          "tabWidth": 2
+        };
+    - path: .gitattributes
+      content: |
+        # No LFS patterns for this stack
+    - path: tools/kernel.config.ts
+      content: |
+        import { defineKernelConfig } from "@warpgogol/werkstatt-engine/kernel/types";
+
+        export default defineKernelConfig({
+          name: "__PROJECT_NAME__",
+          description: "__PROJECT_NAME__ TypeScript TurboRepo workshop",
+          moduleLoaders: {
+            "forge-core": async () => (await import("@warpgogol/forge/os/core")).forgeCoreModule,
+            "forge-rfc": async () => (await import("@warpgogol/forge/os/rfc-module")).forgeRfcModule,
+            "forge-adr": async () => (await import("@warpgogol/forge/os/adr-module")).forgeAdrModule,
+            "forge-plan": async () => (await import("@warpgogol/forge/os/plan-module")).forgePlanModule,
+            "forge-audit": async () => (await import("@warpgogol/forge/os/audit-module")).forgeAuditModule,
+            "forge-compass": async () => (await import("@warpgogol/forge/os/compass")).forgeCompassModule,
+            "forge-naming": async () => (await import("@warpgogol/forge/os/naming-module")).forgeNamingModule,
+            "forge-workflow": async () => (await import("@warpgogol/forge/os/workflow-module")).forgeWorkflowModule,
+            "forge-session": async () => (await import("@warpgogol/forge/os/session-module")).forgeSessionModule,
+            "forge-mission": async () => (await import("@warpgogol/forge/os/mission-module")).forgeMissionModule,
+            "forge-spec": async () => (await import("@warpgogol/forge/os/spec-module")).forgeSpecModule,
+            "forge-exploration": async () => (await import("@warpgogol/forge/os/exploration")).forgeExplorationModule,
+            "forge-program": async () => (await import("@warpgogol/forge/os/program")).forgeProgramModule,
+            "forge-werkstatt": async () => (await import("@warpgogol/forge/os/werkstatt")).forgeWerkstattModule,
+            "typescript-checks": async () => (await import("@warpgogol/werkstatt-typescript/checks/module")).createTypescriptCheckModule(),
+          },
+        });
+    - path: .forge/pinned.yaml
+      content: |
+        # Pinned foundation files (DNA-62, RFC-0733)
+        entries:
+          - path: tools/kernel.config.ts
+            mode: protect
+          - path: forge.yaml
+            mode: protect
+          - path: pnpm-workspace.yaml
+            mode: protect
+          - path: turbo.json
+            mode: protect
+          - path: tsconfig.base.json
+            mode: protect
+    - path: README.md
+      content: |
+        # __PROJECT_NAME__
+
+        A TypeScript TurboRepo workshop powered by the Werkstatt engine.
+
+        ## Prerequisites
+
+        - Node.js 24+
+        - pnpm 10+
+
+        ## Setup
+
+        ### 1. Configure npm token
+
+        Edit `.npmrc` and replace `YOUR_NPM_TOKEN` with a valid npm read token.
+
+        ### 2. Install dependencies
+
+        ```sh
+        pnpm install
+        ```
+
+        ### 3. Verify the workshop
+
+        ```sh
+        pnpm exec forge run forge.doctor
+        pnpm exec forge run forge.validate
+        ```
+
+        ## Stack
+
+        - Engine: @warpgogol/forge
+        - Plugin: @warpgogol/werkstatt-typescript
+        - Stack profile: typescript-turborepo
+install:
+  - pnpm add -wD @warpgogol/forge @warpgogol/werkstatt-typescript @warpgogol/werkstatt-engine @warpgogol/werkstatt-shared prettier vitest typescript

package/src/tests/profile-schema.test.ts

@@ -157,7 +157,7 @@ test("artifacts with missing required extensions field fails", () => {
 
 test("all shipped profiles parse without changes", () => {
   const profiles = listStackProfiles(FORGE_ROOT);
-  expect(profiles.length).toBe(4);
+  expect(profiles.length).toBe(5);
   for (const profile of profiles) {
     expect(profile.id).toBeDefined();
     expect(profile.workspace.dirs.length).toBeGreaterThan(0);

package/src/types/werkstatt-engine-shims.d.ts

@@ -459,6 +459,8 @@ declare module "@warpgogol/werkstatt-engine/mission" {
   export const MissionListData: any;
   export const runMissionMaterialize: any;
   export const MissionMaterializeData: any;
+  export const runMissionMaterializeInternal: any;
+  export const MissionMaterializeInternalOptions: any;
   export const runMissionValidate: any;
   export const MissionValidateData: any;
   export const runMissionBuild: any;
@@ -499,6 +501,10 @@ declare module "@warpgogol/werkstatt-engine/mission" {
   export const runMaterializeConfigValidate: any;
   export const runWorkpieceConfigPresenceCheck: any;
   export const WorkpieceConfigPresenceResult: any;
+  export const runMissionResume: any;
+  export const MissionResumeData: any;
+  export const runMissionJournalShow: any;
+  export const MissionJournalShowData: any;
 }
 
 declare module "@warpgogol/werkstatt-engine/sternsystem" {
@@ -845,6 +851,10 @@ declare module "@warpgogol/werkstatt-engine/nachweis-module" {
   export function createNachweisModule(...args: any[]): any;
 }
 
+declare module "@warpgogol/werkstatt-engine/sichtpass-module" {
+  export function createSichtpassModule(...args: any[]): any;
+}
+
 declare module "@warpgogol/werkstatt-engine/signing" {
   export const generateKeyPair: any;
   export const getPublicKey: any;
@@ -976,6 +986,7 @@ declare module "@warpgogol/werkstatt-engine/agent-gate" {
 declare module "@warpgogol/werkstatt-engine/agent-gate/astro" {
   export function createAgentMcpRoute(...args: any[]): any;
   export function createAgentActionRoute(...args: any[]): any;
+  export function createAgentSearchRoute(...args: any[]): any;
 }
 
 declare module "@warpgogol/werkstatt-engine/changelog" {