@warpgogol/forge 2.20.0 → 2.21.1

package/README.md

@@ -20,7 +20,7 @@ Replace `[describe your project]` with your idea — a game, a library, a knowle
 
 ## What you can build with Forge
 
-Forge supports four kinds of projects. You pick one when you start — everything else is automatic.
+Forge supports five kinds of projects. You pick one when you start — everything else is automatic.
 
 | Project type | What it is | Example ideas |
 | --- | --- | --- |
@@ -28,6 +28,7 @@ Forge supports four kinds of projects. You pick one when you start — everythin
 | **Governance / library** | A code library or governance-only project — no website, no game, no video, just structure and documentation | npm package, internal toolkit, documentation hub |
 | **Godot game** | A desktop or mobile game built with Godot 4.x and C# — 2D, 3D, platformer, RPG | Top-down adventure, 3D platformer, puzzle game |
 | **Knowledge system** | An evidence-backed knowledge base — structured datasets where claims are backed by registered source provenance | Game knowledge base, domain ontology, curated reference dataset |
+| **TypeScript library** | A generic TypeScript monorepo with best-practice validators — tsconfig, import boundaries, phantom deps, package exports, strict mode, barrel safety | Internal toolkit, shared library, TypeScript monorepo |
 
 Each project type gets its own scaffold: the right folder structure, the right dependencies, the right tools. You don't need to know what any of those are — Forge sets them up for you.
 
@@ -46,7 +47,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`) |
+| [`@warpgogol/werkstatt-typescript`](https://github.com/syrokomskyi/werkstatt-typescript) | TypeScript plugin — tsconfig, import boundaries, phantom deps, package exports, strict mode, barrel validators | TypeScript TurboRepo projects (`typescript-turborepo`) |
 
 ### When you need these packages
 

package/README.uk.md

@@ -20,7 +20,7 @@ Install https://npmjs.com/package/@warpgogol/forge in this folder and set up my
 
 ## Що можна створити за допомогою Forge
 
-Forge підтримує чотири типи проєктів. Ви обираєте один на старті — все інше відбувається автоматично.
+Forge підтримує п'ять типів проєктів. Ви обираєте один на старті — все інше відбувається автоматично.
 
 | Тип проєкту | Що це | Приклади |
 | --- | --- | --- |
@@ -28,6 +28,7 @@ Forge підтримує чотири типи проєктів. Ви обира
 | **Управління / бібліотека** | Бібліотека коду або проєкт лише з управлінською структурою — без сайту, без гри, без відео, лише структура та документація | npm-пакет, внутрішній інструмент, центр документації |
 | **Гра Godot** | Десктопна або мобільна гра на Godot 4.x з C# — 2D, 3D, платформер, RPG | Пригода з виглядом зверху, 3D-платформер, головоломка |
 | **Система знань** | База знань з підтримкою доказів — структуровані набори даних, де твердження підтверджені зареєстрованими джерелами | База знань гри, доменна онтологія, куратований довідковий набір даних |
+| **Бібліотека TypeScript** | Універсальний TypeScript монорепозиторій з валідаторами найкращих практик — tsconfig, межі імпортів, фантомні залежності, експорти пакетів, strict mode, безпека barrel-експортів | Внутрішній інструмент, спільна бібліотека, TypeScript монорепозиторій |
 
 Кожен тип проєкту отримує власний каркас: правильну структуру папок, правильні залежності, правильні інструменти. Вам не потрібно знати, що це таке — Forge налаштує все за вас.
 
@@ -46,6 +47,7 @@ Forge — це **шар управління**: навички, RFC/ADR робо
 | [`@warpgogol/werkstatt-phaser-game`](https://github.com/syrokomskyi/werkstatt-phaser-game) | Плагін Phaser-гри — валідатори phaser, збірка Vite, адаптери розгортання | Проєкти браузерних ігор (`phaser-turborepo`) |
 | [`@warpgogol/werkstatt-godot-game`](https://github.com/syrokomskyi/werkstatt-godot-game) | Плагін Godot — валідатори сцен, збірка dotnet, розгортання itch.io, навички Godot | Проєкти ігор Godot (`godot-csharp`) |
 | [`@warpgogol/werkstatt-knowledge`](https://github.com/syrokomskyi/werkstatt-knowledge) | Плагін системи знань — прив'язка джерел, канонічна верифікація, екстракція, матеріалізація, перевірки релізу | Проєкти систем знань (`knowledge-typescript-turborepo`) |
+| [`@warpgogol/werkstatt-typescript`](https://github.com/syrokomskyi/werkstatt-typescript) | Плагін TypeScript — tsconfig, межі імпортів, фантомні залежності, експорти пакетів, strict mode, barrel-валідатори | Проєкти TypeScript TurboRepo (`typescript-turborepo`) |
 
 ### Коли потрібні ці пакети
 
@@ -63,6 +65,9 @@ pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-godot-game
 
 # Проєкт системи знань
 pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-knowledge
+
+# Проєкт TypeScript TurboRepo
+pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-typescript
 ```
 
 > **Примітка для агентів:** Після створення проєкту командою `forge create` завжди встановлюйте рушій та відповідний плагін стеку. Прив'язки в `forge.yaml` посилаються на команди з цих пакунків (напр. `pnpm exec werkstatt run rfc.validate`), і вони не працюватимуть, якщо пакунки не встановлені.
@@ -343,6 +348,7 @@ pnpm exec forge skill.list
 | `phaser-turborepo` | Браузерна гра | Phaser + TypeScript + pnpm + Turborepo | `games/my-game` | Браузерні ігри, інтерактивні досвіди |
 | `godot-csharp` | Гра Godot | Godot 4.x + C# + pnpm + Turborepo | `games/my-game` | Десктопні/мобільні ігри, інтерактивні проєкти на Godot |
 | `knowledge-typescript-turborepo` | Система знань | TypeScript + pnpm + Turborepo | `knowledge/my-kb` | Бази знань з підтримкою доказів, структуровані набори даних з джерельною простежуваністю |
+| `typescript-turborepo` | Бібліотека TypeScript | TypeScript + pnpm + Turborepo | — | Універсальний TypeScript TurboRepo монорепозиторій з валідаторами найкращих практик |
 
 ```sh
 # Список доступних профілів (після встановлення)

package/os/adr/adr.module.ts

@@ -87,6 +87,8 @@ export const forgeAdrModule: ForgeModule = {
 
     registry.registerCommand({
       name: "adr.validate",
+      contract: "adr",
+      rules: [],
       description:
         "Validate ADR frontmatter schema, required markdown sections, " +
         "referential integrity (supersedes/supersededBy), and id/filename consistency. " +

package/os/compass/compass.module.ts

@@ -62,6 +62,8 @@ export const forgeCompassModule: ForgeModule = {
     });
     registry.registerCommand({
       name: "compass.validate",
+      contract: "compass",
+      rules: [],
       description:
         "Validate authored source files against current Compass scaffolding requirements.",
       scope: "workspace",
@@ -77,6 +79,8 @@ export const forgeCompassModule: ForgeModule = {
     });
     registry.registerCommand({
       name: "compass.changesummary.validate",
+      contract: "compass",
+      rules: [],
       description:
         "Validate CHANGE_SUMMARY blocks for boilerplate items and over-cap unprotected items (RFC-0349).",
       scope: "workspace",
@@ -171,6 +175,8 @@ export const forgeCompassModule: ForgeModule = {
     });
     registry.registerCommand({
       name: "compass.audit.validate",
+      contract: "compass",
+      rules: [],
       description:
         "Validate that no authored file is audit-overdue per the revision threshold (RFC-0352). Warns by default, fails with --strict.",
       scope: "workspace",

package/os/core/core.module.ts

@@ -190,6 +190,8 @@ export const forgeCoreModule: ForgeModule = {
     });
     registry.registerCommand({
       name: "forge.skill.validate",
+      contract: "forge",
+      rules: [],
       description:
         "Validate all forge skills against frontmatter contract and invariants SKILL-01..SKILL-20.",
       scope: "workspace",
@@ -209,6 +211,8 @@ export const forgeCoreModule: ForgeModule = {
     });
     registry.registerCommand({
       name: "forge.port.validate",
+      contract: "forge",
+      rules: [],
       description: "Validate a single ported skill or command for compliance with forge contracts.",
       scope: "workspace",
       supportsAllSites: false,
@@ -374,6 +378,8 @@ export const forgeCoreModule: ForgeModule = {
     };
     registry.registerCommand({
       name: "forge.profile.validate",
+      contract: "forge",
+      rules: [],
       description:
         "Validate profile YAML files under packages/forge/profiles/ against the stack-profile schema (RFC-0640).",
       scope: "workspace",
@@ -437,6 +443,8 @@ export const forgeCoreModule: ForgeModule = {
     // ── forge.validate (RFC-0674, RFC-0677) ───────────────────────────────────
     registry.registerCommand({
       name: "forge.validate",
+      contract: "forge",
+      rules: [],
       description:
         "Execute validate commands for all artifacts declared in the active stack profile. Use --dry-run to print resolved commands. Use --artifact to validate a single artifact.",
       scope: "workspace",
@@ -464,6 +472,8 @@ export const forgeCoreModule: ForgeModule = {
     const { runDeterminismCheck } = await import("./handlers/determinism-check.ts");
     registry.registerCommand({
       name: "forge.determinism.check",
+      contract: "forge",
+      rules: [],
       description:
         "Verify artifact determinism by building twice and comparing output hashes. Reads determinism.inputs glob patterns from the active stack profile. Use --dry-run to print resolved inputs, --artifact to check a single artifact.",
       scope: "workspace",
@@ -519,6 +529,8 @@ export const forgeCoreModule: ForgeModule = {
     const { runAssetsCheck } = await import("./handlers/assets-check.ts");
     registry.registerCommand({
       name: "forge.assets.check",
+      contract: "forge",
+      rules: [],
       description:
         "Check for missing, orphaned, and unreferenced assets. Use --strict to fail on orphaned assets, --dry-run to skip hashing.",
       scope: "workspace",
@@ -641,6 +653,8 @@ export const forgeCoreModule: ForgeModule = {
     // ── pinned.validate ─────────────────────────────────────────────────────
     registry.registerCommand({
       name: "pinned.validate",
+      contract: "pinned",
+      rules: [],
       description:
         "Validate working tree against .forge/pinned.yaml manifest. " +
         "Checks staged changes (default) or last commit (--mode ci) for " +
@@ -726,6 +740,8 @@ export const forgeCoreModule: ForgeModule = {
     const { runForgeAutonomyValidate } = await import("./handlers/forge-autonomy-validate.ts");
     registry.registerCommand({
       name: "forge.autonomy.validate",
+      contract: "forge",
+      rules: [],
       description:
         "Scan packages/forge/os/** for forbidden @warpgogol/werkstatt-engine imports outside os/werkstatt/. " +
         "Enforces FORGE-AUTONOMY-01 (RFC-0940, DNA-64). @warpgogol/werkstatt-shared is exempt. " +

package/os/naming/naming.module.ts

@@ -20,6 +20,8 @@ export const forgeNamingModule: ForgeModule = {
     const { runNamingConventionLint } = await import("./naming-convention.ts");
     registry.registerCommand({
       name: "naming.convention.lint",
+      contract: "naming",
+      rules: [],
       description:
         "Validate all filenames use kebab-case (no underscores) across registered workspace roots.",
       scope: "workspace",

package/os/notes/notes.module.ts

@@ -50,6 +50,8 @@ export const forgeNotesModule: ForgeModule = {
 
     registry.registerCommand({
       name: "note.link.validate",
+      contract: "note",
+      rules: [],
       description:
         "Validate wikilink integrity across a markdown note vault. Scans [[wikilinks]] and resolves each against the note graph.",
       scope: "workspace",
@@ -71,6 +73,8 @@ export const forgeNotesModule: ForgeModule = {
 
     registry.registerCommand({
       name: "note.frontmatter.validate",
+      contract: "note",
+      rules: [],
       description:
         "Validate frontmatter consistency across a markdown note vault. Checks for required fields in YAML frontmatter.",
       scope: "workspace",

package/os/plugin/plugin.module.ts

@@ -236,6 +236,8 @@ export const forgePluginModule: ForgeModule = {
   async register(registry) {
     registry.registerCommand({
       name: "forge.plugin.validate",
+      contract: "forge",
+      rules: [],
       description:
         "Validate forge.plugin.yaml manifests for all declared skill packs (RFC-0941). Checks manifest schema (id: kebab-case, version: semver) and reports missing or invalid manifests.",
       scope: "workspace",

package/os/program/program.module.ts

@@ -26,6 +26,8 @@ export const forgeProgramModule: ForgeModule = {
 
     registry.registerCommand({
       name: "program.packet.validate",
+      contract: "program",
+      rules: [],
       description:
         "Validate a program packet against schema, source hashes, branch/head, " +
         "and state machine rules. Read-only. " +

package/os/rfc/acceptance.ts

@@ -158,7 +158,7 @@ async function spawnSiteKernel(
     .trim()
     .split(/\s+/)
     .filter(Boolean);
-  const binPath = path.join(workspaceRoot, "packages", "werkstatt", "bin", "werkstatt.mjs");
+  const binPath = path.join(workspaceRoot, "packages", "werkstatt-engine", "bin", "werkstatt.mjs");
 
   return new Promise((resolve) => {
     const child = spawn(process.execPath, [binPath, ...args], {

package/os/rfc/rfc.module.ts

@@ -114,6 +114,8 @@ export const forgeRfcModule: ForgeModule = {
     // ── rfc.validate ─────────────────────────────────────────────────────────
     registry.registerCommand({
       name: "rfc.validate",
+      contract: "rfc",
+      rules: [],
       description:
         "Validate RFC frontmatter schema, required markdown sections, " +
         "referential integrity (supersedes/supersededBy), date consistency, " +
@@ -130,6 +132,8 @@ export const forgeRfcModule: ForgeModule = {
     // ── rfc.command-lifecycle.validate ───────────────────────────────────────
     registry.registerCommand({
       name: "rfc.command-lifecycle.validate",
+      contract: "rfc",
+      rules: [],
       description:
         "Validate RFC commands.proposed/added/changed/removed lifecycle metadata " +
         "against live registered commands. Emits RFC-CMD-* diagnostics.",
@@ -145,6 +149,8 @@ export const forgeRfcModule: ForgeModule = {
     // ── rfc.check ────────────────────────────────────────────────────────────
     registry.registerCommand({
       name: "rfc.check",
+      contract: "rfc",
+      rules: [],
       description:
         "Validate that artifacts declared by accepted/implemented RFCs exist on disk. " +
         "Checks files from 'File system responsibilities' tables and feature flag references. " +
@@ -184,6 +190,8 @@ export const forgeRfcModule: ForgeModule = {
     // ── rfc.index.validate ───────────────────────────────────────────────────
     registry.registerCommand({
       name: "rfc.index.validate",
+      contract: "rfc",
+      rules: [],
       description:
         "Validate that docs/rfcs/index.yaml exists, is parseable, and its entry count " +
         "matches the number of RFC files on disk. Reports RFC-IDX-01 (missing), " +
@@ -254,6 +262,8 @@ export const forgeRfcModule: ForgeModule = {
     // ── rfc.dna.trace.validate ───────────────────────────────────────────────
     registry.registerCommand({
       name: "rfc.dna.trace.validate",
+      contract: "rfc",
+      rules: [],
       description:
         "RFC-0331: validate the bidirectional DNA-trace matrix — which RFCs satisfy each DNA " +
         "invariant and which invariants each RFC claims to satisfy. Reports DNA-TRACE-01 " +

package/os/session/session.module.ts

@@ -80,6 +80,8 @@ export const forgeSessionModule: ForgeModule = {
 
     registry.registerCommand({
       name: "session.validate",
+      contract: "session",
+      rules: [],
       description:
         "Validate session frontmatter schema (SES-01), id-filename match (SES-02), " +
         "RFC-id existence (SES-03), raw file hygiene (SES-04), and non-markdown " +

package/os/spec/spec.module.ts

@@ -29,6 +29,8 @@ export const forgeSpecModule: ForgeModule = {
 
     registry.registerCommand({
       name: "spec.validate",
+      contract: "spec",
+      rules: [],
       description:
         "Validate vendored spec packages under docs/specs/. " +
         "Checks integrity (SHA-256), schema, dependency graph (acyclic), " +
@@ -123,6 +125,8 @@ export const forgeSpecModule: ForgeModule = {
 
     registry.registerCommand({
       name: "spec.live.validate",
+      contract: "spec",
+      rules: [],
       description:
         "Validate all living feature specs in docs/specs/live/. " +
         "Checks V-LS-01 (frontmatter), V-LS-02 (domain/filename match), " +

package/os/werkstatt/werkstatt.module.ts

@@ -51,6 +51,8 @@ export const forgeWerkstattModule: ForgeModule = {
     });
     registry.registerCommand({
       name: "werkstatt.operation.validate",
+      contract: "werkstatt",
+      rules: [],
       description:
         "Validate that mutating Werkstatt commands use shared lock/idempotency/atomic-write helpers (RFC-0362).",
       scope: "workspace",

package/os/workflow/workflow.module.ts

@@ -22,6 +22,8 @@ export const forgeWorkflowModule: ForgeModule = {
       await import("./handlers.ts");
     registry.registerCommand({
       name: "workflow.lint",
+      contract: "workflow",
+      rules: [],
       description:
         "Validate .agents/workflows AND .agents/workflows-amend markdown frontmatter, command references, " +
         "and per-chain phase links (RFC-0075 + RFC-0136).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "2.20.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/skills/meta/forge-bootstrap/SKILL.md

@@ -136,7 +136,7 @@ Ask the operator:
 1. **Stack** — ask what stack the project uses (TypeScript, Python, Rust, etc.). Write into `forge.yaml` `project.stack`.
 2. **Package manager** — confirm or override `project.packageManager` in `forge.yaml`.
 3. **Stack bindings** — fill `commands.typecheck`, `commands.test`, `commands.scopedBuild` in `forge.yaml`. Ask the operator for the exact commands (e.g. `tsc --noEmit`, `vitest`, `turbo run build`).
-4. **Git init** — check if `.git` exists in the project root. If not, run `git init` and make an initial commit with all project files. If `.git` already exists, proceed.
+4. **Git init** — `forge.create` already initializes git with `--initial-branch=main` programmatically. Verify `.git` exists in the project root. If it does, proceed. If not (e.g. `forge.create` failed to init git), run `git init --initial-branch=main` manually. Make an initial commit with all project files on the `main` branch.
 
 #### Transplant (adapter-driven migration)
 
@@ -168,11 +168,11 @@ The transplant mode performs real code migration via a migration-adapter registr
 
    If yes: the skill uses `git format-patch` (export all commits from source) + `git am` (apply them in the new project) to preserve history without copying the `.git` directory. If the source has many commits, warn that this may take a moment.
 
-   If no: the skill runs `git init` in the new project (clean repository, no history from source).
+   If no: the skill runs `git init --initial-branch=main` in the new project (clean repository, no history from source).
 
-   If git history transfer fails (complex history, submodules, replace objects): warn and continue with a clean `git init`.
+   If git history transfer fails (complex history, submodules, replace objects): warn and continue with a clean `git init --initial-branch=main`.
 
-   If the source project has no `.git` directory: skip the git history question and run `git init` directly.
+   If the source project has no `.git` directory: skip the git history question and run `git init --initial-branch=main` directly.
 
 6. **Post-setup** — call `postSetup()`. The adapter initializes git (clean init or format-patch + git am based on operator's choice), updates `pnpm-workspace.yaml` (adds `apps/<appName>`), `turbo.json` (adds workspace to pipeline), runs the install command derived from `ref(forge.yaml project.packageManager)`. The skill captures bin-link ENOENT warnings from the install output — these are cosmetic and indicate that `dist/` does not exist yet (the project has not been built). If the install itself fails (exit code != 0), report the dependency resolution error in human language (in `aiLanguage`), skip build verification, and continue to the welcoming report. The operator can fix and re-run onboarding.
 
@@ -434,8 +434,8 @@ A short description after every onboarding, read from `forge-about.md`. The skil
 - `doctor` is unavailable → skill skips auto-doctor and notes it in the report; operator can ask the agent to run it later.
 - Auto-ADR creation fails → skill reports the error silently (in agent logs, not to operator), leaves the ADR file in place for the agent to fix, and continues to the welcoming report. The operator is never told about the ADR.
 - Project analysis finds nothing recommendable (transplant) → skill skips recommendations and proceeds to the welcoming report with a direct invitation to start creating.
-- Git history transfer fails → skill warns and continues with clean `git init`.
-- Source project has no `.git` → skill skips the git history question and runs `git init` directly.
+- Git history transfer fails → skill warns and continues with clean `git init --initial-branch=main`.
+- Source project has no `.git` → skill skips the git history question and runs `git init --initial-branch=main` directly.
 - Post-setup `pnpm install` fails → skill reports the error; the operator can fix and re-run `pnpm install` manually.
 - Migration interrupted mid-copy (process crash, agent termination) → `migrate()` is idempotent: re-running skips files that already exist at the target with matching content. The operator can also delete `apps/<appName>/` and re-run for a clean migration.
 - Concurrent execution (two agents running `forge-bootstrap` transplant on the same forge project simultaneously) → the skill does not lock `apps/<appName>/`; concurrent writes may conflict. The operator should not run two transplant operations on the same project in parallel.

package/src/index.ts

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

package/src/migration-adapters/git-utils.ts

@@ -9,6 +9,7 @@
 <CHANGE_SUMMARY>
   <item>RFC-0547: extract shared postSetup git logic from duplicated adapter implementations.</item>
   <item>Replace fs.rmSync with trashSync for patch directory cleanup (trash bin for LLM-initiated deletions).</item>
+  <item>Use --initial-branch=main for all git init calls so new repos default to main instead of master.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -32,7 +33,7 @@ export function runPostSetup(
       execFileSync("git", ["-C", sourceDir, "format-patch", "--all", "-o", patchDir], {
         stdio: "pipe",
       });
-      execFileSync("git", ["init"], { cwd: targetDir, stdio: "pipe" });
+      execFileSync("git", ["init", "--initial-branch=main"], { cwd: targetDir, stdio: "pipe" });
       execFileSync("git", ["config", "user.email", "forge@warpgogol.dev"], {
         cwd: targetDir,
         stdio: "pipe",
@@ -60,12 +61,12 @@ export function runPostSetup(
         `forge: git history transfer failed, falling back to clean git init: ${err instanceof Error ? err.message : String(err)}`,
       );
       if (!fs.existsSync(gitDir)) {
-        execFileSync("git", ["init"], { cwd: targetDir, stdio: "pipe" });
+        execFileSync("git", ["init", "--initial-branch=main"], { cwd: targetDir, stdio: "pipe" });
       }
     }
   } else {
     if (!fs.existsSync(gitDir)) {
-      execFileSync("git", ["init"], { cwd: targetDir, stdio: "pipe" });
+      execFileSync("git", ["init", "--initial-branch=main"], { cwd: targetDir, stdio: "pipe" });
     }
   }
 }

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/create.ts

@@ -17,11 +17,13 @@
   <item>RFC-0643: pass profileId to runInit so forge.yaml gets a `profile` field.</item>
   <item>RFC-0664: scaffold memory layer (.agents/memory/) after init.</item>
   <item>RFC-0877: in-place mode only — --in-place flag required, no subdirectory creation, name derived from folder, strict empty-directory check (only .git/ tolerated).</item>
+  <item>Initialize git repo with --initial-branch=main if .git does not exist (hard guard for main branch default).</item>
 </CHANGE_SUMMARY>
 */
 
 import fs from "node:fs";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 import { stringify as stringifyYaml } from "yaml";
 import { runScaffoldProject } from "./scaffold-project.ts";
 import { runInit, type InitResult, type InitDomainFields } from "./init.ts";
@@ -229,6 +231,23 @@ export async function runCreate(
     };
   }
 
+  // 6.5. Initialize git repo with main branch (if not already initialized)
+  // This is a hard guard — forge.create programmatically ensures main branch,
+  // so greenfield projects don't depend on the agent running git init correctly.
+  const gitDir = path.join(targetDir, ".git");
+  if (!fs.existsSync(gitDir)) {
+    try {
+      execFileSync("git", ["init", "--initial-branch=main"], { cwd: targetDir, stdio: "pipe" });
+      if (outputFormat === "pretty") {
+        logger.info("Initialized git repository with main branch");
+      }
+    } catch {
+      if (outputFormat === "pretty") {
+        logger.warn("Failed to initialize git repository — run 'git init --initial-branch=main' manually");
+      }
+    }
+  }
+
   // 7. Resolve forge root
   let forgeRoot: string;
   if (context.forgeRoot) {

package/src/onboarding/doctor.ts

@@ -23,6 +23,7 @@ Checks for forge.yaml, AGENTS.md, PREFERENCES.md, .agents/skills/, docs/rfcs/,
   <item>RFC-0664: added memory-layer health check (budget usage, gitignore coverage, daily-file leak risk).</item>
   <item>RFC-0704: added independent-version-packages check — validates that paths in independentVersionPackages exist and contain package.json.</item>
   <item>RFC-0941: added pack-manifests advisory check — validates forge.plugin.yaml existence and schema for each declared skill pack.</item>
+  <item>Added git-branch check — warns when current branch is 'master' instead of 'main'.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -1074,6 +1075,39 @@ function checkMemoryLayer(workspaceRoot: string): DoctorCheck {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Git branch check — warn if current branch is 'master' instead of 'main'
+// ---------------------------------------------------------------------------
+
+function checkGitBranch(workspaceRoot: string): DoctorCheck {
+  const gitDir = join(workspaceRoot, ".git");
+  if (!existsSync(gitDir)) {
+    return { name: "git-branch", status: "pass", message: "No git repository — git branch check skipped" };
+  }
+
+  try {
+    const branch = execSync("git branch --show-current", { cwd: workspaceRoot, stdio: "pipe", timeout: 5000 })
+      .toString()
+      .trim();
+
+    if (branch === "master") {
+      return {
+        name: "git-branch",
+        status: "warn",
+        message: "Current branch is 'master' — rename to 'main' with: git branch -m main",
+      };
+    }
+
+    return {
+      name: "git-branch",
+      status: "pass",
+      message: `Current branch: ${branch}`,
+    };
+  } catch {
+    return { name: "git-branch", status: "pass", message: "Unable to determine git branch — check skipped" };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Prerequisite checks (profile-declared system dependencies)
 // ---------------------------------------------------------------------------
@@ -1177,6 +1211,9 @@ export async function runDoctor(
       : "docs/adrs/ directory not found — run 'forge create' to create ADR directory",
   });
 
+  // Check git branch is 'main' (not 'master')
+  checks.push(checkGitBranch(workspaceRoot));
+
   // Check @warpgogol/* forbidden imports (autonomy guard)
   let forgeRoot: string;
   try {

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/tests/migration-adapters.test.ts

@@ -293,6 +293,27 @@ test("migrate excludes .git directory from copy", async () => {
   expect(existsSync(join(appDir, ".git"))).toBe(false);
 });
 
+test("postSetup creates main branch (not master) when gitHistory is false", async () => {
+  const sourceDir = join(tempDir, "source-main");
+  const targetDir = join(tempDir, "target-main");
+
+  await mkdir(sourceDir, { recursive: true });
+  await mkdir(targetDir, { recursive: true });
+  await writeFile(join(sourceDir, "package.json"), JSON.stringify({ name: "test-app" }));
+  await writeFile(join(sourceDir, "tsconfig.json"), "{}");
+  await writeFile(join(sourceDir, "pnpm-lock.yaml"), "");
+
+  const analysis = nodeTypescriptPnpmAdapter.analyze(sourceDir);
+  nodeTypescriptPnpmAdapter.postSetup(sourceDir, targetDir, analysis);
+
+  expect(existsSync(join(targetDir, ".git"))).toBe(true);
+  const { execSync } = await import("node:child_process");
+  const branch = execSync("git branch --show-current", { cwd: targetDir, stdio: "pipe" })
+    .toString()
+    .trim();
+  expect(branch).toBe("main");
+});
+
 test("postSetup runs git init when analysis.gitHistory is false", async () => {
   const sourceDir = join(tempDir, "source");
   const targetDir = join(tempDir, "target");

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

@@ -18,6 +18,10 @@ declare module "@warpgogol/werkstatt-engine/os/werkstatt-commands-validate-modul
   export const werkstattCommandsValidateModule: any;
 }
 
+declare module "@warpgogol/werkstatt-engine/os/werkstatt-e2e-module" {
+  export const werkstattE2eModule: any;
+}
+
 declare module "@warpgogol/werkstatt-engine/kernel" {
   export function discoverSiteWorkspaces(...args: any[]): any;
   export function loadKernelAppConfig(...args: any[]): any;
@@ -36,6 +40,7 @@ declare module "@warpgogol/werkstatt-engine/kernel" {
   export const listRegisteredKernelPipelines: any;
   export const loadAppRuntime: any;
   export const executeKernelCommand: any;
+  export const executeRegisteredCommand: any;
   export const executeKernelPipeline: any;
   export const buildSchedule: any;
   export const executeScheduledSteps: any;
@@ -61,6 +66,8 @@ declare module "@warpgogol/werkstatt-engine/kernel" {
   export interface KernelNextStep {}
   export interface KernelCommandResult {}
   export interface CheckResult {}
+  export interface GeneratedArtifactSpec {}
+  export interface GeneratorOwnershipEntry {}
   export interface KernelRuntimeContext {}
   export interface KernelCommandDefinition {}
   export interface KernelPipelineStep {}
@@ -182,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;
@@ -200,6 +208,7 @@ declare module "@warpgogol/werkstatt-engine/kernel" {
   export const parseNameOnlyOutput: any;
   export const isExempt: any;
   export const pipelineBudgetModule: any;
+  export const validatorInventoryModule: any;
   export const changeImpactModule: any;
   export const commandManifestModule: any;
   export const gitmeshModule: any;
@@ -255,8 +264,7 @@ declare module "@warpgogol/werkstatt-engine/kernel/change-impact-module" {
 }
 
 declare module "@warpgogol/werkstatt-engine/kernel/cli" {
-  const _: any;
-  export = _;
+  export function main(...args: any[]): any;
 }
 
 declare module "@warpgogol/werkstatt-engine/kernel/commit-message" {
@@ -294,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 {}
 }
@@ -340,6 +349,10 @@ declare module "@warpgogol/werkstatt-engine/kernel/pipeline-budgets" {
   export interface PipelineBudgetGenerateResult {}
 }
 
+declare module "@warpgogol/werkstatt-engine/kernel/validator-inventory" {
+  export const validatorInventoryModule: any;
+}
+
 declare module "@warpgogol/werkstatt-engine/kernel/semantic" {
   export const semanticModule: any;
 }
@@ -354,6 +367,7 @@ declare module "@warpgogol/werkstatt-engine/kernel/runtime" {
   export const listRegisteredKernelPipelines: any;
   export const loadAppRuntime: any;
   export const executeKernelCommand: any;
+  export const executeRegisteredCommand: any;
   export const executeKernelPipeline: any;
   export const buildSchedule: any;
   export const executeScheduledSteps: any;
@@ -382,6 +396,8 @@ declare module "@warpgogol/werkstatt-engine/kernel/types" {
   export interface KernelNextStep {}
   export interface KernelCommandResult {}
   export interface CheckResult {}
+  export interface GeneratedArtifactSpec {}
+  export interface GeneratorOwnershipEntry {}
   export interface KernelRuntimeContext {}
   export interface KernelCommandDefinition {}
   export interface KernelPipelineStep {}
@@ -505,10 +521,13 @@ declare module "@warpgogol/werkstatt-engine/mission" {
   export const MissionResumeData: any;
   export const runMissionJournalShow: any;
   export const MissionJournalShowData: any;
+  export const runMissionPreflight: any;
+  export const MissionPreflightInput: any;
+  export const PreflightCheckResult: any;
+  export const MissionPreflightData: any;
 }
 
 declare module "@warpgogol/werkstatt-engine/sternsystem" {
-  export function createSternsystemModule(...args: any[]): any;
   export const runSternsystemRegister: any;
   export const SternsystemRegisterData: any;
   export const runSternsystemList: any;
@@ -525,6 +544,35 @@ declare module "@warpgogol/werkstatt-engine/sternsystem" {
   export const SternsystemStatusData: any;
   export const runSternsystemDiscover: any;
   export const SternsystemDiscoverData: any;
+  export const runSternsystemPassportGenerate: any;
+  export const SternsystemPassportGenerateData: any;
+  export const runSternsystemPassportVerify: any;
+  export const SternsystemPassportVerifyData: any;
+  export const runSternsystemHandoverPrepare: any;
+  export const SternsystemHandoverPrepareData: any;
+  export const runSternsystemHandoverComplete: any;
+  export const SternsystemHandoverCompleteData: any;
+  export const runSternsystemHandoverCancel: any;
+  export const SternsystemHandoverCancelData: any;
+  export const buildPassportPayload: any;
+  export const signPassport: any;
+  export const verifyPassport: any;
+  export const derivePublicKey: any;
+  export const computePassportHash: any;
+  export const SitePassportV1: any;
+  export const SignedSitePassport: any;
+  export const computeAuthorizationHash: any;
+  export const signAuthorization: any;
+  export const verifyAuthorization: any;
+  export const resolveAuthorizationPath: any;
+  export const readAuthorization: any;
+  export const writeAuthorization: any;
+  export const removeAuthorization: any;
+  export const isAuthorizationExpired: any;
+  export const HandoverAuthorizationV1: any;
+  export const SignedHandoverAuthorization: any;
+  export const HandoverCompleteResult: any;
+  export const HandoverEventMetadata: any;
   export const resolveCacheClonePath: any;
   export const resolveWorkpiecePath: any;
   export const readSystemConfig: any;
@@ -549,6 +597,9 @@ declare module "@warpgogol/werkstatt-engine/sternsystem" {
   export const resolveMirrorPath: any;
   export const MirrorResolution: any;
   export const resolveMirrors: any;
+  export const readPassport: any;
+  export const writePassport: any;
+  export const resolvePassportPath: any;
 }
 
 declare module "@warpgogol/werkstatt-engine/bordbuch" {
@@ -622,6 +673,18 @@ declare module "@warpgogol/werkstatt-engine/release" {
   export const runReleaseStateValidate: any;
   export const ReleaseStateValidateData: any;
   export const ReleaseStateCheck: any;
+  export const runBootSmokeCommand: any;
+  export const BootSmokeCommandData: any;
+  export const runBootSmoke: any;
+  export const BootSmokeResult: any;
+  export const BootSmokeRequestSpec: any;
+  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;
 }
 
 declare module "@warpgogol/werkstatt-engine/leitstand" {
@@ -727,15 +790,6 @@ declare module "@warpgogol/werkstatt-engine/handoff" {
   export const hasPlatformScopeFiles: any;
   export const extractTrailer: any;
   export const hasTrailer: any;
-  export const createSternsystemModule: any;
-  export const runSternsystemRegister: any;
-  export const runSternsystemList: any;
-  export const runSternsystemValidate: any;
-  export const runSternsystemPin: any;
-  export const SternsystemRegisterData: any;
-  export const SternsystemListData: any;
-  export const SternsystemValidateData: any;
-  export const SternsystemPinData: any;
   export const runWerkstattLockStatus: any;
   export const WerkstattLockStatusData: any;
   export const runWerkstattLockRecover: any;
@@ -815,6 +869,29 @@ declare module "@warpgogol/werkstatt-engine/leitstand-module" {
   export function createLeitstandModule(...args: any[]): any;
 }
 
+declare module "@warpgogol/werkstatt-engine/fleet" {
+  export const runFleetSitesGenerate: any;
+  export const validateFleetSitesDrift: any;
+  export const FleetSiteRecord: any;
+  export const runFleetApply: any;
+  export const FleetApplyResult: any;
+  export const FleetApplyReportEntry: any;
+  export const registerOwnership: any;
+  export const verifyOwnership: any;
+  export const transferOwnership: any;
+  export const deriveInstanceId: any;
+  export const OwnershipError: any;
+  export const OwnershipClaim: any;
+  export const RegisterResult: any;
+  export const VerifyResult: any;
+  export const TransferResult: any;
+  export const createFleetModule: any;
+}
+
+declare module "@warpgogol/werkstatt-engine/fleet-module" {
+  export function createFleetModule(...args: any[]): any;
+}
+
 declare module "@warpgogol/werkstatt-engine/subdomain-module" {
   export function createSubdomainModule(...args: any[]): any;
 }
@@ -1098,6 +1175,10 @@ declare module "@warpgogol/werkstatt-engine/testing/e2e" {
   export = _;
 }
 
+declare module "@warpgogol/werkstatt-engine/e2e" {
+  export const runColdE2e: any;
+}
+
 declare module "@warpgogol/werkstatt-engine/component-runtime/reflection" {
   export function toReflectedState(...args: any[]): any;
   export function createCapabilityCatalog(...args: any[]): any;

package/src/types.ts

@@ -67,6 +67,10 @@ export interface ForgeCommandMetadata {
   mutatesState?: boolean;
   requiresNetwork?: boolean;
   supportsAllSites?: boolean;
+  /** RFC-0963: validation contract this command belongs to (e.g. "content", "seo"). */
+  contract?: string;
+  /** RFC-0963: rule IDs this validator can emit. Empty for non-emitting validators. */
+  rules?: string[];
   timeoutMs?: number;
   expectedDurationMs?: number;
   longRunning?: boolean;

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,