@warpgogol/forge 2.21.0 → 2.21.1

package/package.json

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

package/profiles/root-agents-godot.md

@@ -4,10 +4,10 @@
      Placeholders: projectName, projectStack, projectPm,
      rfcsDir, adrsDir, plansDir, auditsDir, specsDir,
      skillsDir, dynamicSections -->
+
 # Agent Guide: {{projectName}}
 
-> This file is generated by `forge.agents.generate` from `forge.yaml`.
-> Do not edit by hand — edit `forge.yaml` and regenerate.
+> This file is generated by `forge.agents.generate` from `forge.yaml`. It is a living document — edit freely to add project-specific guidance.
 
 ## Project
 
@@ -52,8 +52,7 @@ dotnet build
 dotnet test
 ```
 
-Run the editor or game through the installed Godot .NET binary.
-Do not change the Godot version, .NET SDK, NuGet packages, or project settings without explicit need.
+Run the editor or game through the installed Godot .NET binary. Do not change the Godot version, .NET SDK, NuGet packages, or project settings without explicit need.
 
 ## C# Rules
 
@@ -103,6 +102,7 @@ Before completing a task:
 - When facing an unclear architectural decision, propose options and ask for direction first.
 
 {{dynamicSections}}
+
 ## RTK — Token Optimization
 
 Always prefix shell commands with `rtk` to minimize token consumption. RTK filters and compresses command output before it reaches the LLM context, cutting up to 90% of bash output on common operations.

package/src/index.ts

@@ -43,6 +43,7 @@ export {
   writeFileAtomic,
   type WriteFileAtomicOptions,
   GENERATED_MARKER,
+  EDITABLE_GENERATED_MARKER,
   hasGeneratedMarker,
   stripGeneratedMarker,
   buildGeneratedHeader,

package/src/onboarding/agents-generate.ts

@@ -266,6 +266,7 @@ export async function runAgentsGenerate(
     filePath: "AGENTS.md",
     ownerCommand: "forge.agents.generate",
     commandPrefix: "forge",
+    editable: true,
   });
 
   // RFC-0643: determine register from PREFERENCES.md or profile

package/src/onboarding/nested-agents-templates.ts

@@ -184,6 +184,7 @@ export function buildNestedAgentsMd(
     filePath: "AGENTS.md",
     ownerCommand: "forge.agents.generate",
     commandPrefix: "forge",
+    editable: true,
   });
 
   const lines: string[] = [];
@@ -200,7 +201,7 @@ export function buildNestedAgentsMd(
   }
 
   lines.push(`> This file is generated by \`forge.agents.generate\`.`);
-  lines.push(`> Do not edit by hand — re-run \`forge agents generate\` to regenerate.`);
+  lines.push(`> It is a living document — edit freely to add workspace-specific guidance.`);
   lines.push("");
 
   lines.push(`**Workspace type:** ${TYPE_LABEL[workspace.type]}`);

package/src/onboarding/templates/root-agents-business.md

@@ -7,7 +7,7 @@
 # Agent Guide: {{projectName}}
 
 > This file is generated by `forge.agents.generate` from `forge.yaml`.
-> Do not edit by hand — edit `forge.yaml` and regenerate.
+> It is a living document — edit freely to add project-specific guidance.
 
 ## Project
 

package/src/onboarding/templates/root-agents-creative.md

@@ -7,7 +7,7 @@
 # Agent Guide: {{projectName}}
 
 > This file is generated by `forge.agents.generate` from `forge.yaml`.
-> Do not edit by hand — edit `forge.yaml` and regenerate.
+> It is a living document — edit freely to add project-specific guidance.
 
 ## Project
 

package/src/tests/fixtures/agents-generate-business-before.txt

@@ -1,6 +1,6 @@
 <!--
-  GENERATED. Do not change this line unless the file contains project specific changes.
-  DO NOT EDIT THIS FILE. Changes are overwritten on the next build.
+  GENERATED. Safe to edit — project-specific changes are expected and encouraged.
+  This file is generated but editable — your changes are preserved on regeneration.
   Owner command: forge.agents.generate
   Edit instead: the forge.agents.generate generator source (not this file).
   Regenerate:   forge forge.agents.generate
@@ -16,7 +16,7 @@
 # Agent Guide: test-project
 
 > This file is generated by `forge.agents.generate` from `forge.yaml`.
-> Do not edit by hand — edit `forge.yaml` and regenerate.
+> It is a living document — edit freely to add project-specific guidance.
 
 ## Project
 

package/src/tests/generated-marker.test.ts

@@ -1,6 +1,7 @@
 import { test, expect, describe } from "vitest";
 import {
   GENERATED_MARKER,
+  EDITABLE_GENERATED_MARKER,
   hasGeneratedMarker,
   stripGeneratedMarker,
   buildGeneratedHeader,
@@ -141,6 +142,19 @@ describe("buildGeneratedHeader", () => {
     });
     expect(header).toContain("Edit instead: templates/foo.ts");
   });
+
+  test("editable mode uses permissive marker and advisory", () => {
+    const header = buildGeneratedHeader({
+      filePath: "AGENTS.md",
+      ownerCommand: "forge.agents.generate",
+      editable: true,
+    });
+    expect(header).toContain(EDITABLE_GENERATED_MARKER);
+    expect(header).not.toContain(GENERATED_MARKER);
+    expect(header).not.toContain("DO NOT EDIT");
+    expect(header).toContain("Safe to edit");
+    expect(header).toContain("editable");
+  });
 });
 
 describe("isGeneratedMarkerTextCandidate", () => {

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

@@ -189,6 +189,7 @@ declare module "@warpgogol/werkstatt-engine/kernel" {
   export const WriteFileAtomicOptions: any;
   export const writeFileIfChanged: any;
   export const GENERATED_MARKER: any;
+  export const EDITABLE_GENERATED_MARKER: any;
   export const hasGeneratedMarker: any;
   export const stripGeneratedMarker: any;
   export const isGeneratedMarkerTextCandidate: any;
@@ -301,6 +302,7 @@ declare module "@warpgogol/werkstatt-engine/kernel/generated-marker" {
   export function buildGeneratedHeader(...args: any[]): any;
   export function isGeneratedMarkerTextCandidate(...args: any[]): any;
   export const GENERATED_MARKER: any;
+  export const EDITABLE_GENERATED_MARKER: any;
   export interface StripGeneratedMarkerResult {}
   export interface GeneratedHeaderInput {}
 }
@@ -679,6 +681,9 @@ declare module "@warpgogol/werkstatt-engine/release" {
   export const BootSmokeRequestResult: any;
   export const planBootSmokeRequests: any;
   export const detectBootSmokeLanguages: any;
+  export const resolveWranglerConfig: any;
+  export const resolveLanguages: any;
+  export const WranglerResolution: any;
   export const simulateBindings: any;
 }
 

package/src/utils/generated-marker.ts

@@ -10,14 +10,22 @@ source (dependency inversion).</purpose>
 <CHANGE_SUMMARY>
   <item>Moved from @warpgogol/site-kernel/generated-marker to forge as canonical source.</item>
   <item>Added optional commandPrefix to GeneratedHeaderInput — defaults to "forge" for autonomous mode; site-kernel passes "pnpm exec werkstatt run".</item>
+  <item>Added editable flag to GeneratedHeaderInput — when true, emits a permissive marker and advisory that encourages agents to edit the file. AGENTS.md files use editable: true; other generated files keep the restrictive marker.</item>
 </CHANGE_SUMMARY>
 */
 
 export const GENERATED_MARKER =
   "GENERATED. Do not change this line unless the file contains project specific changes.";
 
+export const EDITABLE_GENERATED_MARKER =
+  "GENERATED. Safe to edit — project-specific changes are expected and encouraged.";
+
+const DO_NOT_EDIT_LINE = "DO NOT EDIT THIS FILE. Changes are overwritten on the next build.";
+const SAFE_TO_EDIT_LINE =
+  "This file is generated but editable — your changes are preserved on regeneration.";
+
 export function hasGeneratedMarker(content: string): boolean {
-  return content.includes(GENERATED_MARKER);
+  return content.includes(GENERATED_MARKER) || content.includes(EDITABLE_GENERATED_MARKER);
 }
 
 export interface StripGeneratedMarkerResult {
@@ -29,10 +37,7 @@ function escapeRegex(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-const DO_NOT_EDIT_LINE = "DO NOT EDIT THIS FILE. Changes are overwritten on the next build.";
-
 export function stripGeneratedMarker(content: string): StripGeneratedMarkerResult {
-  const raw = GENERATED_MARKER;
   let result = content;
   let changed = false;
 
@@ -46,38 +51,43 @@ export function stripGeneratedMarker(content: string): StripGeneratedMarkerResul
     }
   };
 
-  applyAll([
-    new RegExp(`<!--[ \\t]*\\n[\\s\\S]*?${escapeRegex(raw)}[\\s\\S]*?-->\\n?`, "g"),
-    new RegExp(`/\\*[ \\t]*\\n[\\s\\S]*?${escapeRegex(raw)}[\\s\\S]*?\\*/\\n?`, "g"),
-  ]);
-
-  for (const token of ["//", "#"]) {
-    const t = escapeRegex(token);
-    const advisoryLine = (suffix: string): string => `(?:[ \\t]*${t}[ \\t]*${suffix}\\n)?`;
-    const pattern = new RegExp(
-      `^[ \\t]*${t}[ \\t]*${escapeRegex(raw)}\\n` +
-        advisoryLine(escapeRegex(DO_NOT_EDIT_LINE)) +
-        advisoryLine("Owner command:.*") +
-        advisoryLine("Edit instead:.*") +
-        advisoryLine("Regenerate:.*"),
-      "gm",
-    );
-    applyAll([pattern]);
-  }
+  for (const [raw, advisory] of [
+    [GENERATED_MARKER, DO_NOT_EDIT_LINE],
+    [EDITABLE_GENERATED_MARKER, SAFE_TO_EDIT_LINE],
+  ] as const) {
+    applyAll([
+      new RegExp(`<!--[ \\t]*\\n[\\s\\S]*?${escapeRegex(raw)}[\\s\\S]*?-->\\n?`, "g"),
+      new RegExp(`/\\*[ \\t]*\\n[\\s\\S]*?${escapeRegex(raw)}[\\s\\S]*?\\*/\\n?`, "g"),
+    ]);
+
+    for (const token of ["//", "#"]) {
+      const t = escapeRegex(token);
+      const advisoryLine = (suffix: string): string => `(?:[ \\t]*${t}[ \\t]*${suffix}\\n)?`;
+      const pattern = new RegExp(
+        `^[ \\t]*${t}[ \\t]*${escapeRegex(raw)}\\n` +
+          advisoryLine(escapeRegex(advisory)) +
+          advisoryLine("Owner command:.*") +
+          advisoryLine("Edit instead:.*") +
+          advisoryLine("Regenerate:.*"),
+        "gm",
+      );
+      applyAll([pattern]);
+    }
 
-  applyAll([
-    new RegExp(`^\\s*<!--\\s*${escapeRegex(raw)}\\s*-->\\n?`, "gm"),
-    new RegExp(`^\\s*//\\s*${escapeRegex(raw)}\\n?`, "gm"),
-    new RegExp(`^\\s*/\\*\\s*${escapeRegex(raw)}\\s*\\*/\\n?`, "gm"),
-    new RegExp(`^\\s*#\\s*${escapeRegex(raw)}\\n?`, "gm"),
-    new RegExp(`^\\s*${escapeRegex(raw)}\\n?`, "gm"),
-  ]);
+    applyAll([
+      new RegExp(`^\\s*<!--\\s*${escapeRegex(raw)}\\s*-->\\n?`, "gm"),
+      new RegExp(`^\\s*//\\s*${escapeRegex(raw)}\\n?`, "gm"),
+      new RegExp(`^\\s*/\\*\\s*${escapeRegex(raw)}\\s*\\*/\\n?`, "gm"),
+      new RegExp(`^\\s*#\\s*${escapeRegex(raw)}\\n?`, "gm"),
+      new RegExp(`^\\s*${escapeRegex(raw)}\\n?`, "gm"),
+    ]);
 
-  if (result.includes(raw)) {
-    const next = result.split(raw).join("");
-    if (next !== result) {
-      changed = true;
-      result = next;
+    if (result.includes(raw)) {
+      const next = result.split(raw).join("");
+      if (next !== result) {
+        changed = true;
+        result = next;
+      }
     }
   }
 
@@ -94,6 +104,12 @@ export interface GeneratedHeaderInput {
    * Site-kernel callers pass "pnpm exec werkstatt run" for Warpgogol context.
    */
   commandPrefix?: string;
+  /**
+   * When true, emits a permissive marker and advisory lines that encourage agents
+   * to edit the file. Used for AGENTS.md files that are generated but should be
+   * freely editable by agents working on the project. Defaults to false.
+   */
+  editable?: boolean;
 }
 
 type GeneratedHeaderCommentStyle = "line-slash" | "line-hash" | "block-html" | "block-css";
@@ -119,6 +135,9 @@ function commentStyleForPath(filePath: string): GeneratedHeaderCommentStyle {
 export function buildGeneratedHeader(input: GeneratedHeaderInput): string {
   const style = commentStyleForPath(input.filePath);
   const prefix = input.commandPrefix ?? "forge";
+  const editable = input.editable ?? false;
+  const marker = editable ? EDITABLE_GENERATED_MARKER : GENERATED_MARKER;
+  const advisoryLine = editable ? SAFE_TO_EDIT_LINE : DO_NOT_EDIT_LINE;
   const regenerateCommand = input.site
     ? `${prefix} ${input.ownerCommand} --site ${input.site}`
     : `${prefix} ${input.ownerCommand}`;
@@ -127,8 +146,8 @@ export function buildGeneratedHeader(input: GeneratedHeaderInput): string {
     : `Edit instead: the ${input.ownerCommand} generator source (not this file).`;
 
   const lines = [
-    GENERATED_MARKER,
-    DO_NOT_EDIT_LINE,
+    marker,
+    advisoryLine,
     `Owner command: ${input.ownerCommand}`,
     editInstead,
     `Regenerate:   ${regenerateCommand}`,

package/src/utils/index.ts

@@ -15,6 +15,7 @@ export { writeFileAtomic, type WriteFileAtomicOptions } from "./fs-atomic.ts";
 export { writeFileIfChanged } from "./fs-idempotent.ts";
 export {
   GENERATED_MARKER,
+  EDITABLE_GENERATED_MARKER,
   hasGeneratedMarker,
   stripGeneratedMarker,
   buildGeneratedHeader,