@warpgogol/forge 5.3.2 → 5.3.4

package/skills/fo/fo-idea-plan/SKILL.md

@@ -182,15 +182,26 @@ The grilling checks:
 
 Address every concern the grilling raises by revising the draft. Do not persist until the grilling is satisfied.
 
-### 5b. Summit suggestion
+### 5b. Summit decision (autonomous)
 
-If the RFC meets summit criteria (any of: `kind: architecture` AND `scope: workspace`, `satisfies[]` includes 2+ DNA invariants, introduces a new package/command/lifecycle, supersedes an implemented RFC), suggest using `fo-design-summit` before acceptance. Use `ask_user_question`:
+Decide yourself whether to run `fo-design-summit` before persisting the plan. **Do not ask the operator** — the planning agent holds the full context and is best placed to judge. The operator can always request a summit explicitly.
 
-> "This RFC is complex (architecture, workspace scope, 2+ DNA invariants). Should I run a multi-persona design summit before acceptance?"
+Eligibility — the RFC meets **any** of:
 
-Recommended option: "Run summit" — because complex RFCs benefit from multi-perspective review.
+- `kind: architecture` AND `scope: workspace`
+- `satisfies[]` includes 2+ DNA invariants
+- Introduces a new package, command family, or lifecycle
+- Supersedes an implemented RFC
 
-If the operator declines, proceed to step 6. If the operator accepts, invoke `fo-design-summit` via the `skill` tool, wait for it to complete, then proceed to step 6.
+Eligibility alone is not sufficient — most RFCs meet at least one criterion mechanically. Run the summit only when multi-perspective review is likely to surface findings that the audit, enhance, and grilling steps did not:
+
+- The design holds genuinely contested trade-offs or more than one viable architecture.
+- There is cross-cutting risk a single-perspective pass misses (security or privacy surface, migration of already-implemented behavior, multi-workspace blast radius).
+- Step 3 or the grilling left material questions unresolved.
+
+Skip the summit when the change is additive, follows an established pattern, or the plan converged cleanly — meeting a criterion only technically (e.g. listing 2 DNA invariants on a routine change) is a skip. When in doubt, skip: a missed summit is recoverable, operator attention is not.
+
+If you run it, announce in one line (`Running design summit — <reason>`), invoke `fo-design-summit` via the `skill` tool, wait for it to complete, then proceed to step 6. If you skip, emit one line (`Design summit skipped — <reason>`) and proceed directly to step 6.
 
 ### 6. Persist the plan
 

package/skills/fo/fo-session-retro/SKILL.md

@@ -450,7 +450,7 @@ If any operator insights were routed to `.agents/operator-profile.md`, offer the
 
 Present a concise summary in `aiLanguage`. **ALL labels, headings, column names, and prose MUST be translated to `aiLanguage`** — the template below is structural only. Only identifiers (file paths, skill names, RFC/ADR ids, commit hashes) stay untranslated. This is non-negotiable: an English summary when `aiLanguage` is `ru` is a violation of this skill's language contract.
 
-**Engineering Checkpoint (RFC-0884):** The closing block follows the Engineering Checkpoint protocol defined in `_shared/fo-session-summary.md`. The agent MUST:
+**Engineering Checkpoint:** The closing block follows the Engineering Checkpoint protocol defined in `_shared/fo-session-summary.md`. The agent MUST:
 
 1. **Select mode** — analyze the session's changes. If the session changed architecture, runtime flow, state machines, persistence models, or public contracts, use **full mode** (6 sections). Otherwise, use **lightweight mode** (3 sections).
 2. **Diagram selection** (full mode only) — apply the diagram selection rules table from `_shared/fo-session-summary.md` to determine if a Mermaid diagram is warranted. If no structural change warrants a diagram, explicitly state "No diagram: this session did not change system structure..."

package/skills/fo/fo-session-save/SKILL.md

@@ -60,7 +60,7 @@ Enhance saved session transcripts with semantic annotations, summaries, and qual
 
 6. **Update the session file:**
    - Update frontmatter: `summary`, `decisions`, refined `types`, corrected metadata.
-   - **Checkpoint fields (RFC-0884):** When the session produced substantial engineering work, populate the optional checkpoint frontmatter fields:
+   - **Checkpoint fields:** When the session produced substantial engineering work, populate the optional checkpoint frontmatter fields:
      - `checkpoint` — object with `before`, `change`, `after` (each 1-2 sentences describing state N, what was done, state N+1)
      - `systemDelta` — object with arrays: `changedContracts`, `changedSchemas`, `changedStateMachines`, `changedInvariants`, `changedPersistence`
      - `diagrams` — array of objects: `type` (flowchart/sequenceDiagram/stateDiagram-v2/erDiagram/none), `scope` (current-system/session-delta), `caption`, `mermaid` (Mermaid syntax or empty string)

package/src/config/forge-config.ts

@@ -6,7 +6,6 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0661: added optional knowledge.budgets binding for hot/warm layer character budget overrides.</item>
   <item>RFC-0662: added optional knowledge.retentionDays and knowledge.staleDays bindings for compaction overrides.</item>
   <item>RFC-0704: added optional independentVersionPackages field to forgeConfigSchema for packages with autonomous npm versions.</item>
   <item>RFC-1097: step 6 — compass.migrate codemod run
@@ -15,14 +14,15 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
   <item>RFC-1097: sweep — packages/forge + services clean
 
 Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PURPOSE-02), headers on mission/index + gen-upstreams, sanitizeItemText in summary.record (literal Compass tags corrupted history), excludedPaths for wrangler types, test-fixtures testPattern. forge+services now 0 diagnostics under --mode error.</item>
-  <history>RFC-0391, RFC-0393, RFC-0537, RFC-0538, RFC-0539, RFC-0540, RFC-0543, RFC-0546, RFC-0639, RFC-0640, RFC-0643</history>
+  <item>RFC-1224: preserve operator forge.yaml content on upgrade, promote adrImplementStamp binding</item>
+  <history>RFC-0391, RFC-0393, RFC-0537, RFC-0538, RFC-0539, RFC-0540, RFC-0543, RFC-0546, RFC-0639, RFC-0640, RFC-0643, RFC-0661, RFC-1224</history>
 </CHANGE_SUMMARY>
 */
 
 import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { z } from "zod";
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml, parseDocument } from "yaml";
 import {
   TERMINOLOGY_DEFAULTS,
   compassPolicyOverridesSchema,
@@ -36,22 +36,27 @@ import { listStackProfiles, type StackProfile } from "../profiles/stack-profile.
 
 export const forgeBindingsSchema = z.object({
   schema: z.literal("forge/bindings@1"),
-  commands: z.object({
-    validateRfc: z.string().nullable().default(null),
-    validateAdr: z.string().nullable().default(null),
-    implementStamp: z.string().nullable().default(null),
-    typecheck: z.string().nullable().default(null),
-    test: z.string().nullable().default(null),
-    scopedBuild: z.string().nullable().default(null),
-    specValidate: z.string().nullable().default(null),
-    sessionSave: z.string().nullable().default(null),
-    // Semantic keys (RFC-0639) — domain-neutral, optional
-    validate: z.string().nullable().default(null),
-    produce: z.string().nullable().default(null),
-    verify: z.string().nullable().default(null),
-    preview: z.string().nullable().default(null),
-    lint: z.string().nullable().default(null),
-  }),
+  commands: z
+    .object({
+      validateRfc: z.string().nullable().default(null),
+      validateAdr: z.string().nullable().default(null),
+      implementStamp: z.string().nullable().default(null),
+      adrImplementStamp: z.string().nullable().default(null),
+      typecheck: z.string().nullable().default(null),
+      test: z.string().nullable().default(null),
+      scopedBuild: z.string().nullable().default(null),
+      specValidate: z.string().nullable().default(null),
+      sessionSave: z.string().nullable().default(null),
+      // Semantic keys (RFC-0639) — domain-neutral, optional
+      validate: z.string().nullable().default(null),
+      produce: z.string().nullable().default(null),
+      verify: z.string().nullable().default(null),
+      preview: z.string().nullable().default(null),
+      lint: z.string().nullable().default(null),
+      // RFC-1224: consumer-defined command keys (e.g. createRfc) stay in the
+      // parsed config so resolveBinding can resolve them.
+    })
+    .passthrough(),
   paths: z.object({
     invariantsFile: z.string().nullable().default(null),
     compassDocs: z.array(z.string()).default([]),
@@ -98,6 +103,7 @@ export interface ForgeBindings {
     validateRfc: string | null;
     validateAdr: string | null;
     implementStamp: string | null;
+    adrImplementStamp: string | null;
     typecheck: string | null;
     test: string | null;
     scopedBuild: string | null;
@@ -177,44 +183,48 @@ export interface ForgeMigrationAdapter {
 // Schema (forge/config@1)
 // ---------------------------------------------------------------------------
 
-export const forgeConfigSchema = z.object({
-  schema: z.literal("forge/config@1"),
-  project: z.object({
-    name: z.string().min(1),
-    stack: z.array(z.string()).default([]),
-    packageManager: z.enum(["pnpm", "npm", "yarn", "bun", "none"]).default("pnpm"),
-    // RFC-0640: optional domain field — absent means software-domain fallback
-    domain: z.string().optional(),
-  }),
-  paths: z.object({
-    rfcsDir: z.string().default("docs/rfcs"),
-    adrsDir: z.string().default("docs/adrs"),
-    plansDir: z.string().default("docs/plans"),
-    auditsDir: z.string().default("docs/audits"),
-    specsDir: z.string().default("docs/specs"),
-    skillsDir: z.string().default(".agents/skills"),
-    sessionsDir: z.string().default("docs/sessions"),
-  }),
-  /** Bindings contract (RFC-0393). Optional — absent means no bindings. */
-  bindings: forgeBindingsSchema.optional(),
-  /** Skill packs (RFC-0539). Optional — absent means no project-local packs. */
-  skillPacks: z.array(forgeSkillPackSchema).optional(),
-  /** Migration adapters (RFC-0546). Optional — absent means built-in adapters only. */
-  migrationAdapters: z.array(forgeMigrationAdapterSchema).optional(),
-  /** Forge sync metadata (RFC-0543). Optional — absent means never synced. */
-  forge: z
-    .object({
-      syncedVersion: z.string().nullable().default(null),
-    })
-    .optional(),
-  /** RFC-0643: profile id — when present, loadForgeConfig loads the corresponding profiles/<id>.yaml */
-  // RFC-1118: accept the corrupted object form (whole StackProfile written by a
-  // previous buggy serialize) so loadForgeConfig can recover the declared id —
-  // a hard schema throw here would deadlock `forge upgrade`, the healing path.
-  profile: z.union([z.string(), z.object({ id: z.string().min(1) }).passthrough()]).optional(),
-  /** RFC-0704: packages with autonomous npm versions — ecosystem.commit skips platform bump when all staged files belong to these packages */
-  independentVersionPackages: z.array(z.string()).optional(),
-});
+export const forgeConfigSchema = z
+  .object({
+    schema: z.literal("forge/config@1"),
+    project: z.object({
+      name: z.string().min(1),
+      stack: z.array(z.string()).default([]),
+      packageManager: z.enum(["pnpm", "npm", "yarn", "bun", "none"]).default("pnpm"),
+      // RFC-0640: optional domain field — absent means software-domain fallback
+      domain: z.string().optional(),
+    }),
+    paths: z.object({
+      rfcsDir: z.string().default("docs/rfcs"),
+      adrsDir: z.string().default("docs/adrs"),
+      plansDir: z.string().default("docs/plans"),
+      auditsDir: z.string().default("docs/audits"),
+      specsDir: z.string().default("docs/specs"),
+      skillsDir: z.string().default(".agents/skills"),
+      sessionsDir: z.string().default("docs/sessions"),
+    }),
+    /** Bindings contract (RFC-0393). Optional — absent means no bindings. */
+    bindings: forgeBindingsSchema.optional(),
+    /** Skill packs (RFC-0539). Optional — absent means no project-local packs. */
+    skillPacks: z.array(forgeSkillPackSchema).optional(),
+    /** Migration adapters (RFC-0546). Optional — absent means built-in adapters only. */
+    migrationAdapters: z.array(forgeMigrationAdapterSchema).optional(),
+    /** Forge sync metadata (RFC-0543). Optional — absent means never synced. */
+    forge: z
+      .object({
+        syncedVersion: z.string().nullable().default(null),
+      })
+      .optional(),
+    /** RFC-0643: profile id — when present, loadForgeConfig loads the corresponding profiles/<id>.yaml */
+    // RFC-1118: accept the corrupted object form (whole StackProfile written by a
+    // previous buggy serialize) so loadForgeConfig can recover the declared id —
+    // a hard schema throw here would deadlock `forge upgrade`, the healing path.
+    profile: z.union([z.string(), z.object({ id: z.string().min(1) }).passthrough()]).optional(),
+    /** RFC-0704: packages with autonomous npm versions — ecosystem.commit skips platform bump when all staged files belong to these packages */
+    independentVersionPackages: z.array(z.string()).optional(),
+    // RFC-1224: consumer-owned top-level sections (e.g. `plugins:`) stay in the
+    // parsed config so full-serialization writes do not silently drop them.
+  })
+  .passthrough();
 
 export interface ForgeConfig {
   schema: "forge/config@1";
@@ -268,6 +278,10 @@ export const FORGE_CLI_BINDING_DEFAULTS: ForgeCliBindingDefault[] = [
     key: "commands.implementStamp",
     template: "forge rfc.implement.stamp --id {id} --implementation-commit {commit}",
   },
+  {
+    key: "commands.adrImplementStamp",
+    template: "forge adr.implement.stamp --id {id} --implementation-commit {commit}",
+  },
   { key: "commands.specValidate", template: "forge spec.validate --spec={id} --json" },
   { key: "commands.sessionSave", template: "forge session.save --json" },
 ];
@@ -302,6 +316,7 @@ export function applyCliBindingDefaults(pm: string): ForgeBindings["commands"] {
     validateRfc: null,
     validateAdr: null,
     implementStamp: null,
+    adrImplementStamp: null,
     typecheck: null,
     test: null,
     scopedBuild: null,
@@ -471,6 +486,36 @@ export function serializeForgeConfig(config: ForgeConfig): Record<string, unknow
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// YAML document patching — RFC-1224
+// ---------------------------------------------------------------------------
+
+/**
+ * A single targeted write into forge.yaml: a dotted key path expressed as
+ * segments plus the value to set. `applyForgeYamlPatches` creates missing
+ * intermediate maps and preserves comments/formatting elsewhere in the file.
+ */
+export interface ForgeYamlPatch {
+  path: string[];
+  value: unknown;
+}
+
+/**
+ * Apply targeted patches to a forge.yaml document without rewriting it.
+ * Returns the patched YAML text, or null when the document cannot be parsed —
+ * callers should fall back to full serialization in that case.
+ */
+export function applyForgeYamlPatches(rawYaml: string, patches: ForgeYamlPatch[]): string | null {
+  const doc = parseDocument(rawYaml);
+  if (doc.errors.length > 0) {
+    return null;
+  }
+  for (const patch of patches) {
+    doc.setIn(patch.path, patch.value);
+  }
+  return doc.toString();
+}
+
 // ---------------------------------------------------------------------------
 // Forge root resolver — the single place that decides monorepo vs npm-installed
 // ---------------------------------------------------------------------------

package/src/onboarding/create.ts

@@ -9,7 +9,6 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <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>RFC-1097: step 6 — compass.migrate codemod run
@@ -18,7 +17,8 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
   <item>RFC-1097: sweep — packages/forge + services clean
 
 Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PURPOSE-02), headers on mission/index + gen-upstreams, sanitizeItemText in summary.record (literal Compass tags corrupted history), excludedPaths for wrangler types, test-fixtures testPattern. forge+services now 0 diagnostics under --mode error.</item>
-  <history>RFC-0544, RFC-0548, RFC-0550, RFC-0640</history>
+  <item>RFC-1224: preserve operator forge.yaml content on upgrade, promote adrImplementStamp binding</item>
+  <history>RFC-0544, RFC-0548, RFC-0550, RFC-0640, RFC-0643, RFC-1224</history>
 </CHANGE_SUMMARY>
 */
 
@@ -32,6 +32,7 @@ import { scaffoldMemoryLayer } from "./memory-scaffold.ts";
 import {
   loadForgeConfig,
   serializeForgeConfig,
+  applyForgeYamlPatches,
   resolveForgeRoot,
   resolvePackageManager,
   applyCliBindingDefaults,
@@ -346,15 +347,30 @@ export async function runCreate(
     const forgeYamlPath = path.join(targetDir, "forge.yaml");
     if (await fio.exists(forgeYamlPath)) {
       try {
-        const config = loadForgeConfig(targetDir);
         const pm = resolvePackageManager(packageManager);
-        config.project.packageManager = pm;
-        if (config.bindings) {
-          config.bindings.commands = applyCliBindingDefaults(pm);
+        const commandDefaults = applyCliBindingDefaults(pm);
+        // RFC-1224: patch the document init just wrote instead of re-serializing —
+        // preserves comments/formatting and any schema-unknown sections.
+        const raw = await fio.readFile(forgeYamlPath);
+        const patched = applyForgeYamlPatches(raw, [
+          { path: ["project", "packageManager"], value: pm },
+          ...Object.entries(commandDefaults).map(([key, value]) => ({
+            path: ["bindings", "commands", key],
+            value,
+          })),
+        ]);
+        if (patched !== null) {
+          await fio.writeFile(forgeYamlPath, patched);
+        } else {
+          const config = loadForgeConfig(targetDir);
+          config.project.packageManager = pm;
+          if (config.bindings) {
+            config.bindings.commands = commandDefaults;
+          }
+          // RFC-1118: serializeForgeConfig writes the declared profile id verbatim —
+          // never the resolved StackProfile object, never drops an unresolvable id.
+          await fio.writeFile(forgeYamlPath, stringifyYaml(serializeForgeConfig(config)));
         }
-        // RFC-1118: serializeForgeConfig writes the declared profile id verbatim —
-        // never the resolved StackProfile object, never drops an unresolvable id.
-        await fio.writeFile(forgeYamlPath, stringifyYaml(serializeForgeConfig(config)));
       } catch {
         // Post-processing is best-effort — init already wrote a valid config
       }

package/src/onboarding/doctor.ts

@@ -8,7 +8,6 @@ Checks for forge.yaml, AGENTS.md, PREFERENCES.md, .agents/skills/, docs/rfcs/,
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <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>RFC-1097: step 6 — compass.migrate codemod run
@@ -17,7 +16,9 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
   <item>RFC-1097: sweep — packages/forge + services clean
 
 Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PURPOSE-02), headers on mission/index + gen-upstreams, sanitizeItemText in summary.record (literal Compass tags corrupted history), excludedPaths for wrangler types, test-fixtures testPattern. forge+services now 0 diagnostics under --mode error.</item>
-  <history>RFC-0391, RFC-0393, RFC-0524, RFC-0539, RFC-0540, RFC-0611, RFC-0640, RFC-0660, RFC-0661, RFC-0663, RFC-0675</history>
+  <item>RFC-1224: preserve operator forge.yaml content on upgrade, promote adrImplementStamp binding</item>
+  <item>RFC-1226: skills-unmanaged check — warn on SKILL.md-bearing dirs without .forge-managed marker</item>
+  <history>RFC-0391, RFC-0393, RFC-0524, RFC-0539, RFC-0540, RFC-0611, RFC-0640, RFC-0660, RFC-0661, RFC-0663, RFC-0664, RFC-0675, RFC-1224</history>
 </CHANGE_SUMMARY>
 */
 
@@ -54,6 +55,7 @@ import { compactMemoryMd } from "./memory-compact.ts";
 import { checkInvariants } from "./invariant-engine.ts";
 import type { InvariantViolation } from "./invariant-engine.ts";
 import { checkNpmToken, workshopNeedsWarpgogolToken } from "./npm-token-check.ts";
+import { SKILL_MARKER_FILE } from "./skill-markers.ts";
 import { execSync } from "../utils/sync-fs.ts";
 import * as fs from "../utils/sync-fs.ts";
 import type { ProfilePrerequisite } from "../profiles/profile-schema.ts";
@@ -142,6 +144,7 @@ const BINDING_COMMAND_KEYS = [
   "commands.validateRfc",
   "commands.validateAdr",
   "commands.implementStamp",
+  "commands.adrImplementStamp",
   "commands.typecheck",
   "commands.test",
   "commands.scopedBuild",
@@ -762,6 +765,49 @@ async function checkPackSkills(workspaceRoot: string, io: WorkspaceIO): Promise<
   };
 }
 
+// ---------------------------------------------------------------------------
+// Unmanaged skill directories (RFC-1226)
+// ---------------------------------------------------------------------------
+
+// Visibility only: a dir bearing SKILL.md without .forge-managed is
+// consumer-owned per RFC-1154 — report it, never prune or block.
+async function checkUnmanagedSkillDirs(workspaceRoot: string, io: WorkspaceIO): Promise<DoctorCheck> {
+  let config;
+  try {
+    config = loadForgeConfig(workspaceRoot);
+  } catch {
+    return { name: "skills-unmanaged", status: "pass", message: "No forge.yaml — unmanaged skill dir check skipped" };
+  }
+
+  const skillsDir = join(workspaceRoot, config.paths.skillsDir);
+  let entries;
+  try {
+    entries = await io.readdir(skillsDir);
+  } catch {
+    return { name: "skills-unmanaged", status: "pass", message: "skillsDir absent — nothing to scan" };
+  }
+
+  const unmanaged: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory) continue;
+    const dir = join(skillsDir, entry.name);
+    // Support dirs (_shared/, knowledge-only dirs) are not skills — skip.
+    if (!(await io.exists(join(dir, "SKILL.md")))) continue;
+    if (await io.exists(join(dir, SKILL_MARKER_FILE))) continue;
+    unmanaged.push(entry.name);
+  }
+
+  if (unmanaged.length === 0) {
+    return { name: "skills-unmanaged", status: "pass", message: "all skill dirs forge-managed" };
+  }
+
+  return {
+    name: "skills-unmanaged",
+    status: "warn",
+    message: `${unmanaged.length} unmanaged skill dir(s): ${unmanaged.join(", ")} — consumer-owned (no ${SKILL_MARKER_FILE} marker). Port into a declared skillPacks pack to make them forge-managed, or leave as-is.`,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Pack manifest diagnostics (RFC-0941)
 // ---------------------------------------------------------------------------
@@ -1455,6 +1501,9 @@ export async function runDoctor(
   const packManifestCheck = await checkPackManifests(workspaceRoot, fio);
   checks.push(packManifestCheck);
 
+  // RFC-1226: List unmanaged skill dirs under skillsDir (visibility only)
+  checks.push(await checkUnmanagedSkillDirs(workspaceRoot, fio));
+
   // RFC-0704: Check independent version packages — paths must exist and contain package.json
   const independentCheck = await checkIndependentVersionPackages(workspaceRoot, fio);
   checks.push(independentCheck);

package/src/onboarding/upgrade.ts

@@ -11,7 +11,6 @@ With --update-npm, also updates @warpgogol/forge from npm before syncing (skippe
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0611: added nested AGENTS.md generation after skill sync.</item>
   <item>RFC-0663: added syncSharedKnowledge step to sync shared knowledge layer to .agents/skills/shared-knowledge/.</item>
   <item>RFC-0664: added scaffoldMemoryLayer step to scaffold .agents/memory/ and .gitignore block.</item>
   <item>RFC-1097: step 6 — compass.migrate codemod run
@@ -20,7 +19,8 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
   <item>RFC-1097: sweep — werkstatt-engine clean
 
 Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
-  <history>RFC-0543</history>
+  <item>RFC-1224: preserve operator forge.yaml content on upgrade, promote adrImplementStamp binding</item>
+  <history>RFC-0543, RFC-0611, RFC-1224</history>
 </CHANGE_SUMMARY>
 */
 
@@ -35,10 +35,12 @@ import {
   resolveForgeRoot,
   loadForgeConfig,
   serializeForgeConfig,
+  applyForgeYamlPatches,
   resolvePmRunner,
   resolvePmInstall,
   type ForgeConfig,
   type ForgeBindings,
+  type ForgeYamlPatch,
 } from "../config/forge-config.ts";
 import { FORGE_SKILLS, discoverPackSkills } from "../registry.ts";
 import { syncKnowledgeFile } from "../knowledge/index.ts";
@@ -452,18 +454,38 @@ async function updateSyncedVersion(
   workspaceRoot: string,
   config: ForgeConfig,
   version: string,
+  bindingsAdded: { key: string; value: string }[],
   dryRun: boolean,
   io: WorkspaceIO,
+  warn: (msg: string) => void,
 ): Promise<void> {
   if (dryRun) return;
 
-  // Set the syncedVersion on the in-memory config (bindings already updated)
+  // Keep the in-memory config truthful for downstream steps (doctor).
   config.forge = { syncedVersion: version };
 
-  // Write the full config back to forge.yaml
+  // RFC-1224: patch the existing document — syncedVersion plus newly added
+  // binding defaults — instead of re-serializing, so consumer-owned keys,
+  // sections, comments and ordering survive the rewrite.
+  const patches: ForgeYamlPatch[] = [
+    { path: ["forge", "syncedVersion"], value: version },
+    ...bindingsAdded.map((b) => ({
+      path: ["bindings", ...b.key.split(".")],
+      value: b.value,
+    })),
+  ];
+  const forgeYamlPath = path.join(workspaceRoot, "forge.yaml");
+  const raw = await io.readFile(forgeYamlPath).catch(() => null);
+  const patched = raw === null ? null : applyForgeYamlPatches(raw, patches);
+  if (patched !== null) {
+    await io.writeFile(forgeYamlPath, patched);
+    return;
+  }
+  warn(
+    "forge.upgrade: forge.yaml patch failed — falling back to full serialization (schema-unknown keys may be dropped)",
+  );
   // RFC-1118: serializeForgeConfig writes the declared profile id verbatim —
   // never the resolved StackProfile object, never drops an unresolvable id.
-  const forgeYamlPath = path.join(workspaceRoot, "forge.yaml");
   await io.writeFile(forgeYamlPath, stringifyYaml(serializeForgeConfig(config)));
 }
 
@@ -689,7 +711,15 @@ export async function runUpgrade(
 
   // Step 5: Update forge.syncedVersion
   if (!isDryRun) {
-    await updateSyncedVersion(workspaceRoot, config, toVersion, false, fio);
+    await updateSyncedVersion(
+      workspaceRoot,
+      config,
+      toVersion,
+      bindingsAdded,
+      false,
+      fio,
+      (msg) => context.logger.warn(msg),
+    );
   }
 
   // Step 5b: Generate nested AGENTS.md (RFC-0611). RFC-1153: the write path

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

@@ -7,6 +7,8 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0639: initial test suite for semantic command keys, terminology resolution, and applyCliBindingDefaults.</item>
+  <item>RFC-1224: adrImplementStamp schema/default coverage; consumer-defined command key passthrough.</item>
+  <item>RFC-1224: preserve operator forge.yaml content on upgrade, promote adrImplementStamp binding</item>
 </CHANGE_SUMMARY>
 */
 
@@ -174,12 +176,14 @@ describe("RFC-0639: Terminology schema change", () => {
 });
 
 describe("RFC-0639: applyCliBindingDefaults", () => {
-  test("returns 13 keys with semantic keys as null", () => {
+  test("returns 14 keys with semantic keys as null", () => {
     const commands = applyCliBindingDefaults("pnpm");
     // CLI-backed keys are non-null
     expect(commands.validateRfc).not.toBeNull();
     expect(commands.validateAdr).not.toBeNull();
     expect(commands.implementStamp).not.toBeNull();
+    // RFC-1224: adr.implement.stamp promoted to a first-class default binding
+    expect(commands.adrImplementStamp).not.toBeNull();
     expect(commands.specValidate).not.toBeNull();
     expect(commands.sessionSave).not.toBeNull();
     // Software-domain keys are null
@@ -312,3 +316,51 @@ describe("RFC-0639: resolveTerminology", () => {
     expect(resolveTerminology(config, undefined, "source")).toBe("source file");
   });
 });
+
+describe("RFC-1224: promoted + consumer-defined command keys", () => {
+  test("forgeBindingsSchema accepts adrImplementStamp", () => {
+    const result = forgeBindingsSchema.safeParse({
+      schema: "forge/bindings@1",
+      commands: {
+        adrImplementStamp:
+          "pnpm exec forge adr.implement.stamp --id {id} --implementation-commit {commit}",
+      },
+      paths: {
+        invariantsFile: null,
+        compassDocs: [],
+        reviewsDir: null,
+        handoffsDir: null,
+        sessionsDir: null,
+      },
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.commands.adrImplementStamp).toBe(
+        "pnpm exec forge adr.implement.stamp --id {id} --implementation-commit {commit}",
+      );
+    }
+  });
+
+  test("forgeBindingsSchema retains consumer-defined command keys", () => {
+    const result = forgeBindingsSchema.safeParse({
+      schema: "forge/bindings@1",
+      commands: {
+        validateRfc: null,
+        createRfc: "pnpm exec forge rfc.create",
+      },
+      paths: {
+        invariantsFile: null,
+        compassDocs: [],
+        reviewsDir: null,
+        handoffsDir: null,
+        sessionsDir: null,
+      },
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect((result.data.commands as Record<string, unknown>)["createRfc"]).toBe(
+        "pnpm exec forge rfc.create",
+      );
+    }
+  });
+});

package/src/tests/doctor-bindings.test.ts

@@ -4,6 +4,8 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0540: initial doctor binding notices tests.</item>
+  <item>RFC-1224: adrImplementStamp added to notice inventory and fixtures.</item>
+  <item>RFC-1224: preserve operator forge.yaml content on upgrade, promote adrImplementStamp binding</item>
 </CHANGE_SUMMARY>
 */
 
@@ -58,7 +60,7 @@ async function setupMinimalProject(dir: string): Promise<void> {
   await writeFile(join(dir, "PREFERENCES.md"), "# Test", "utf8");
 }
 
-test("doctor emits defaultable-binding-null notices for all 5 forge-CLI bindings when null", async () => {
+test("doctor emits defaultable-binding-null notices for all 6 forge-CLI bindings when null", async () => {
   await setupMinimalProject(tempDir);
   await writeForgeYaml(
     tempDir,
@@ -96,11 +98,12 @@ bindings:
 
   const result = await runDoctor({ argv: [], flags: {} }, mockContext(tempDir));
   const notices = result.data?.bindings?.notices ?? [];
-  expect(notices).toHaveLength(5);
+  expect(notices).toHaveLength(6);
   const keys = notices.map((n) => n.key);
   expect(keys).toContain("commands.validateRfc");
   expect(keys).toContain("commands.validateAdr");
   expect(keys).toContain("commands.implementStamp");
+  expect(keys).toContain("commands.adrImplementStamp");
   expect(keys).toContain("commands.specValidate");
   expect(keys).toContain("commands.sessionSave");
   for (const notice of notices) {
@@ -131,6 +134,7 @@ bindings:
     validateRfc: "custom rfc validate command"
     validateAdr: "custom adr validate command"
     implementStamp: "custom stamp command"
+    adrImplementStamp: "custom adr stamp command"
     typecheck: null
     test: null
     scopedBuild: null
@@ -172,6 +176,7 @@ bindings:
     validateRfc: "npx forge rfc.validate --id {id} --json"
     validateAdr: "npx forge adr.validate --id {id} --json"
     implementStamp: "npx forge rfc.implement.stamp --id {id} --implementation-commit {commit}"
+    adrImplementStamp: "npx forge adr.implement.stamp --id {id} --implementation-commit {commit}"
     typecheck: null
     test: null
     scopedBuild: null