@warpgogol/forge 5.2.3 → 5.3.0

package/skills/shared/grilling/learned-principles.archive.md

@@ -1,7 +1,9 @@
 <!-- knowledge-layer: L2 -->
+
 # learned-principles.md (archive)
 
 Archived entries from learned-principles.md. Generated by forge.skill.knowledge.compact (RFC-0662).
+
 ### K-0001: Extend infrastructure before feature logic
 
 ```knowledge-entry
@@ -15,6 +17,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0003.
+
 ### K-0002: Unknown is not green
 
 ```knowledge-entry
@@ -28,6 +31,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0001.
+
 ### K-0003: Quality claims bind to immutable identity
 
 ```knowledge-entry
@@ -41,6 +45,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0001.
+
 ### K-0004: Evaluation must not mutate its subject
 
 ```knowledge-entry
@@ -54,6 +59,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0004.
+
 ### K-0005: Immutable history and current health are separate
 
 ```knowledge-entry
@@ -67,6 +73,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0001.
+
 ### K-0006: Migration complexity follows the real estate
 
 ```knowledge-entry
@@ -80,6 +87,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0003.
+
 ### K-0007: Integrity requires an independent authority
 
 ```knowledge-entry
@@ -93,6 +101,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0002.
+
 ### K-0008: Historical verification preserves policy bytes
 
 ```knowledge-entry
@@ -106,6 +115,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0001.
+
 ### K-0009: Distributed evidence uses authority order and immutable cuts
 
 ```knowledge-entry
@@ -119,6 +129,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0002.
+
 ### K-0010: Bootstrap safety does not create legacy authority
 
 ```knowledge-entry
@@ -132,6 +143,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0003.
+
 ### K-0011: Documents are execution boundaries
 
 ```knowledge-entry
@@ -145,6 +157,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0005.
+
 ### K-0012: Supersede decision authority, preserve useful mechanisms deliberately
 
 ```knowledge-entry
@@ -158,6 +171,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0003.
+
 ### K-0013: Deterministic aggregators need scale contracts
 
 ```knowledge-entry
@@ -171,6 +185,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0006.
+
 ### K-0014: Canonical identities require a closed snapshot boundary
 
 ```knowledge-entry
@@ -184,6 +199,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0007.
+
 ### K-0015: Permanent formats profile standards instead of imitating them
 
 ```knowledge-entry
@@ -197,6 +213,7 @@ status: superseded
 ```
 
 Promoted to shared layer as shared/K-0007.
+
 ### K-0016: Cutover enforcement starts after executor bootstrap
 
 ```knowledge-entry

package/skills/shared/grilling/learned-principles.md

@@ -10,4 +10,3 @@ Concrete principles distilled from past grilling sessions. Each principle has a
 - **confirmations:** <N>
 - **Added:** <date>
 -->
-

package/skills/shared/knowledge/learned-principles.md

@@ -18,6 +18,7 @@ status: active
 
 - **Condition:** A consequential durable decision depends on evidence, policy, or artifact state that may later change or become unavailable.
 - **Recommended answer:** Represent missing, stale, malformed, or unavailable evidence explicitly and fail closed. Bind the decision to immutable subject and policy bytes, preserve its evidence as append-only history, and calculate current health separately rather than rewriting the historical result.
+
 ### K-0002: Integrity requires authority ordering
 
 ```knowledge-entry
@@ -32,6 +33,7 @@ status: active
 
 - **Condition:** Evidence or events may be produced concurrently, retried, submitted by the artifact author, delivered out of order, or received after a decision closes.
 - **Recommended answer:** Admit evidence through a separate least-privilege authority that assigns a monotonic sequence and freezes every decision at an explicit evaluation cut. Producer timestamps never determine precedence, self-authored consistency is not authority, and late results create a new decision or incident instead of rewriting history.
+
 ### K-0003: Forward-only cutovers preserve recovery, not legacy authority
 
 ```knowledge-entry
@@ -46,6 +48,7 @@ status: active
 
 - **Condition:** A forward-only transition replaces an authority model, runtime, toolchain, or deployment contract while still requiring prerequisites and a recoverable first cutover.
 - **Recommended answer:** Provision and verify the required executor and infrastructure before activating enforcement. Then supersede the old authority through the smallest complete cutover that fits the real estate. Preserve useful old mechanisms only as explicitly non-authorizing infrastructure; permit a narrow, one-time rollback target with explicit closure conditions, never an indefinite compatibility path.
+
 ### K-0004: Evaluation must not mutate its subject
 
 ```knowledge-entry
@@ -60,6 +63,7 @@ status: active
 
 - **Condition:** A gate, evaluator, audit, review, or certification process discovers a defect in the artifact it judges.
 - **Recommended answer:** Keep evaluation read-only with respect to the judged artifact. Emit precise, anchored remediation tasks; apply fixes in a separate authoring flow that produces a new artifact identity and a new evidence chain.
+
 ### K-0005: Documents are executable boundaries
 
 ```knowledge-entry
@@ -74,6 +78,7 @@ status: active
 
 - **Condition:** A specification or implementation document will be executed by another agent—possibly less capable—in an isolated session.
 - **Recommended answer:** Decompose work into dependency-ordered documents that each define their inputs, outputs, forbidden shortcuts, acceptance evidence, and bounded validation. Every document must leave its affected scope internally consistent; use a final integration document for cross-module laws instead of relying on unstated context.
+
 ### K-0006: Deterministic mechanisms require scale contracts
 
 ```knowledge-entry
@@ -88,6 +93,7 @@ status: active
 
 - **Condition:** A deterministic evaluator, selector, validator, or aggregator processes potentially growing collections and may gate a consequential transition.
 - **Recommended answer:** Specify hard input limits, time and memory complexity, overflow behavior, and a deterministic stress fixture. Reject overflow explicitly without truncation or synthesized success, and forbid repeated full scans when an indexed or single-pass design is available.
+
 ### K-0007: Canonical identities use closed snapshots and named standards
 
 ```knowledge-entry

package/skills/shared/my-preferences/SKILL.md

@@ -7,6 +7,7 @@ concerns: document-only
 dependsOn: []
 languagePolicy: ref(PREFERENCES.md)
 ---
+
 <!--
 <MODULE_CONTRACT>
 <purpose>my-preferences skill — Read, create, or edit the operator's preferences file at the repository root. Run when the operator wants to change language settings for AI conversations, grilling, or project documentation.</purpose>
@@ -21,7 +22,6 @@ Sweep batch 1: add Compass v2 headers to 45 SKILL.md files (purpose derived from
 </CHANGE_SUMMARY>
 -->
 
-
 # my-preferences
 
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing, create it using the semantics below.

package/skills/shared/windows-ai-tooling/SKILL.md

@@ -7,6 +7,7 @@ concerns: code-mutation
 dependsOn: []
 languagePolicy: ref(PREFERENCES.md)
 ---
+
 <!--
 <MODULE_CONTRACT>
 <purpose>windows-ai-tooling skill — Bootstrap a Windows project for AI agents. Installs verified tools, generates .gitattributes, and emits a command allow-list for agent prompts. Run when starting a new project or when agents fail.</purpose>
@@ -21,7 +22,6 @@ Sweep batch 1: add Compass v2 headers to 45 SKILL.md files (purpose derived from
 </CHANGE_SUMMARY>
 -->
 
-
 # Windows AI Tooling
 
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.

package/skills/shared/writing-great-skills/SKILL.md

@@ -7,6 +7,7 @@ concerns: read-only
 dependsOn: []
 languagePolicy: ref(PREFERENCES.md)
 ---
+
 <!--
 <MODULE_CONTRACT>
 <purpose>writing-great-skills skill — Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.</purpose>
@@ -21,7 +22,6 @@ Sweep batch 1: add Compass v2 headers to 45 SKILL.md files (purpose derived from
 </CHANGE_SUMMARY>
 -->
 
-
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
 
 A skill exists to wrangle determinism out of a stochastic system. **Predictability** — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it.

package/src/compass/contract-registry.ts

@@ -12,7 +12,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import picomatch from "picomatch";

package/src/config/forge-config.ts

@@ -19,7 +19,7 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { z } from "zod";
 import { parse as parseYaml } from "yaml";
@@ -83,6 +83,13 @@ export const forgeBindingsSchema = z.object({
       budget: z.number().int().positive().default(4096),
     })
     .optional(),
+  // RFC-1150: consumer-declared directory names excluded from workspace
+  // discovery (merged over the SKIP_DIRS defaults in workspace-discovery.ts).
+  workspaces: z
+    .object({
+      skipDirs: z.array(z.string()).default([]),
+    })
+    .optional(),
 });
 
 export interface ForgeBindings {
@@ -126,6 +133,10 @@ export interface ForgeBindings {
   memory?: {
     budget: number;
   };
+  // RFC-1150: consumer-declared workspace discovery exclusions
+  workspaces?: {
+    skipDirs: string[];
+  };
 }
 
 // ---------------------------------------------------------------------------

package/src/knowledge/__tests__/sync.test.ts

@@ -24,8 +24,7 @@ afterEach(() => {
 });
 
 function entry(id: string, title: string, body: string, layer = "L0"): string {
-  const confirmations =
-    layer === "L2" ? `lastConfirmedAt: 2026-08-03\nconfirmations: 1\n` : "";
+  const confirmations = layer === "L2" ? `lastConfirmedAt: 2026-08-03\nconfirmations: 1\n` : "";
   return `### ${id}: ${title}\n\n\`\`\`knowledge-entry\nid: ${id}\nlayer: ${layer}\ncreated: 2026-08-03\n${confirmations}status: active\n\`\`\`\n\n${body}\n`;
 }
 
@@ -99,11 +98,7 @@ test("merges: local entries preserved, new source entries appended", () => {
 test("merge into empty template appends all source entries", () => {
   const src = join(tempDir, "qa-log.md");
   const dest = join(tempDir, "dest.md");
-  writeFileSync(
-    src,
-    knowledgeFile("L0", [entry("K-0001", "First", "Body one.")]),
-    "utf8",
-  );
+  writeFileSync(src, knowledgeFile("L0", [entry("K-0001", "First", "Body one.")]), "utf8");
   // Destination is the shipped empty template (layer marker, no entries)
   writeFileSync(dest, `<!-- knowledge-layer: L0 -->\n\n# Q&A Log (L0)\n`, "utf8");
 

package/src/knowledge/budgets.ts

@@ -13,7 +13,7 @@
 */
 
 import path from "node:path";
-import { readFileSync } from "node:fs";
+import { readFileSync } from "../utils/sync-fs.ts";
 import { parse as parseYaml } from "yaml";
 import type { ParsedKnowledgeFile, KnowledgeLayer } from "./schema.ts";
 

package/src/knowledge/compact.ts

@@ -13,7 +13,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import type { ParsedKnowledgeFile, KnowledgeEntry, KnowledgeEntryMeta } from "./schema.ts";

package/src/knowledge/parse.ts

@@ -11,7 +11,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import {

package/src/knowledge/sync.ts

@@ -12,11 +12,11 @@ the synced copy with the package version.</purpose>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>2026-09-24: initial append-only knowledge sync — merge by entry-ID union, local wins conflicts, skip divergent non-cumulative files, recurse into declared directories.</item>
+  <item>RFC-0660: initial append-only knowledge sync — merge by entry-ID union, local wins conflicts, skip divergent non-cumulative files, recurse into declared directories.</item>
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { parseKnowledgeFile } from "./parse.ts";
 import { serializeKnowledgeFile } from "./serialize.ts";
@@ -80,9 +80,7 @@ function planFileSync(srcPath: string, destPath: string): KnowledgeSyncPlan {
   if (isCumulative(srcParsed) && isCumulative(destParsed)) {
     const destIds = new Set(destParsed.entries.map((e) => e.meta.id));
     const appendedEntries = srcParsed.entries.filter((e) => !destIds.has(e.meta.id));
-    const conflicts = srcParsed.entries
-      .filter((e) => destIds.has(e.meta.id))
-      .map((e) => e.meta.id);
+    const conflicts = srcParsed.entries.filter((e) => destIds.has(e.meta.id)).map((e) => e.meta.id);
 
     const destLegacyTexts = new Set(destParsed.legacySections.map((l) => l.text.trim()));
     const appendedLegacy = srcParsed.legacySections.filter(

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

@@ -17,9 +17,9 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+import { execFileSync } from "../utils/sync-fs.ts";
 import { trashSync } from "../utils/fs-trash-sync.ts";
 import type { AdapterAnalysis } from "./types.ts";
 

package/src/migration-adapters/ignored-files.ts

@@ -16,9 +16,9 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+import { execFileSync } from "../utils/sync-fs.ts";
 
 export type IgnoredFileCategoryId = "config" | "data" | "runtime-state" | "cache" | "other";
 

package/src/migration-adapters/node-typescript-pnpm/index.ts

@@ -13,7 +13,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../../utils/sync-fs.ts";
 import path from "node:path";
 import type { MigrationAdapter, AdapterAnalysis, MigrationResult, Conflict } from "../types.ts";
 import { FORGE_PROTECTED_PATHS, DEFAULT_EXCLUDE_PATTERNS } from "../types.ts";

package/src/migration-adapters/phaser-pnpm/index.ts

@@ -13,7 +13,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../../utils/sync-fs.ts";
 import path from "node:path";
 import type { MigrationAdapter, AdapterAnalysis, MigrationResult, Conflict } from "../types.ts";
 import { FORGE_PROTECTED_PATHS, DEFAULT_EXCLUDE_PATTERNS } from "../types.ts";