@warpgogol/forge 4.1.6 → 4.2.1

package/docs/reference/forge-yaml.md

@@ -0,0 +1,114 @@
+# forge.yaml reference
+
+## Full schema
+
+```yaml
+schema: forge/config@1
+project:
+  name: my-project          # Required. Project name.
+  stack: [typescript]        # Required. List of stack identifiers.
+  packageManager: pnpm      # Required. Currently only "pnpm" is supported.
+paths:
+  rfcsDir: docs/rfcs         # Default: docs/rfcs
+  adrsDir: docs/adrs         # Default: docs/adrs
+  skillsDir: .agents/skills  # Default: .agents/skills
+bindings:
+  schema: forge/bindings@1
+  commands:
+    validateRfc: "forge rfc.validate {id} --json"
+    typecheck: "pnpm run build:check"
+    test: "pnpm test"
+  paths:
+    invariantsFile: docs/architecture-dna.md
+  terminology:
+    invariants: DNA
+skillPacks:
+  - prefix: wg
+    dir: packages/my-skills/skills
+plugins: []
+syncedVersion: 4.1.6
+```
+
+## project
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | yes | Project name, used in generated AGENTS.md and CI |
+| `stack` | string[] | yes | Stack identifiers (e.g. `[typescript]`, `[phaser]`) |
+| `packageManager` | string | yes | Package manager (`pnpm` only) |
+
+## paths
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `rfcsDir` | `docs/rfcs` | Directory for RFC files |
+| `adrsDir` | `docs/adrs` | Directory for ADR files |
+| `skillsDir` | `.agents/skills` | Directory for deployed skills |
+
+## bindings.commands
+
+A map of named commands to shell strings. The agent uses these to run project-specific operations. Placeholders like `{id}` are substituted at resolve time.
+
+```yaml
+bindings:
+  commands:
+    validateRfc: "forge rfc.validate {id} --json"
+    typecheck: "pnpm run build:check"
+    test: "pnpm test"
+```
+
+## bindings.paths
+
+Additional path bindings that the agent can reference:
+
+```yaml
+bindings:
+  paths:
+    invariantsFile: docs/architecture-dna.md
+```
+
+## bindings.terminology
+
+Maps generic terms to project-specific names:
+
+```yaml
+bindings:
+  terminology:
+    invariants: DNA
+```
+
+## skillPacks
+
+Optional. Declares project-local skill packs:
+
+```yaml
+skillPacks:
+  - prefix: wg               # Cannot be "fo" (reserved)
+    dir: packages/my-skills/skills
+```
+
+Each pack directory must contain a `forge.plugin.yaml` manifest with `id` and `version` fields.
+
+## Extension points
+
+Packs can declare custom Compass contract blocks:
+
+```yaml
+# In forge.plugin.yaml
+extensionPoints:
+  compass:
+    contract:
+      blocks:
+        - blockId: api-contract
+          requiredFor:
+            - "packages/my-pack/**/*.ts"
+          requiredTags:
+            - name: purpose
+              minWords: 3
+```
+
+`compass.validate` enforces these blocks with `COMPASS-PLUGIN-01` (missing block), `COMPASS-PLUGIN-02` (missing tag), and `COMPASS-PLUGIN-03` (below minWords) diagnostics.
+
+## syncedVersion
+
+Set by `forge upgrade`. Tracks the last synced Forge version. Do not edit manually.

package/docs/reference/profiles.md

@@ -0,0 +1,37 @@
+# Stack profiles
+
+A stack profile defines the project scaffold: directory structure, dependencies, CI config, and first workspace.
+
+## Available profiles
+
+| Profile | Project type | First workspace | Use case |
+| --- | --- | --- | --- |
+| `forge-shell` | Governance / library | — | Governance-only projects, libraries, non-web projects |
+| `typescript-turborepo` | TypeScript library | — | Generic TypeScript Turborepo monorepo with validators |
+| `phaser-turborepo` | Browser game | `games/my-game` | Browser games, interactive experiences |
+| `godot-csharp` | Godot game | `games/my-game` | Desktop/mobile games, Godot-based projects |
+| `knowledge-typescript-turborepo` | Knowledge system | `knowledge/my-kb` | Evidence-backed knowledge bases |
+
+## Using a profile
+
+```sh
+pnpm dlx @warpgogol/forge@latest create --in-place --profile phaser-turborepo
+```
+
+## Listing profiles
+
+```sh
+pnpm exec forge profile.validate
+```
+
+## Auto-detection during transplant
+
+When bringing an existing project through the `/forge-bootstrap` transplant mode, Forge detects the matching profile by checking for marker files:
+
+- `phaser.config.*` → `phaser-turborepo`
+- `project.godot` → `godot-csharp`
+- `tsconfig.json` + `pnpm-workspace.yaml` → `typescript-turborepo`
+
+## Project-agnostic
+
+Forge is project-agnostic. Stack profiles provide ready-made starting points, but the governance layer (RFCs, ADRs, skills, validators) works the same regardless of the profile.

package/docs/reference/programmatic-api.md

@@ -0,0 +1,79 @@
+# Programmatic API
+
+## Importing
+
+```ts
+import {
+  forgeCoreModule,
+  forgeRfcModule,
+  forgeAdrModule,
+  forgeNamingModule,
+  forgeCompassModule,
+  forgeWorkflowModule,
+  forgeSpecModule,
+  forgeSessionModule,
+  forgePluginModule,
+  forgeProgramModule,
+  loadForgeConfig,
+  resolveBinding,
+  FORGE_SKILLS,
+} from "@warpgogol/forge";
+```
+
+## Loading config
+
+```ts
+const config = loadForgeConfig(process.cwd());
+```
+
+Returns a typed `ForgeConfig` object, or throws if `forge.yaml` is missing or invalid.
+
+## Resolving bindings
+
+```ts
+const cmd = resolveBinding(config, "commands.validateRfc", { id: "RFC-0001" });
+// → "forge rfc.validate RFC-0001 --json"
+```
+
+Placeholders in binding strings are substituted with the provided values.
+
+## Registering modules
+
+```ts
+const registry = /* your ForgeModuleRegistry */;
+
+await forgeCoreModule.register(registry);
+await forgeRfcModule.register(registry);
+await forgeAdrModule.register(registry);
+await forgeNamingModule.register(registry);
+await forgeCompassModule.register(registry);
+```
+
+Each module registers its commands with the registry. Modules are independent — register only what you need.
+
+## Available modules
+
+| Module | Commands |
+| --- | --- |
+| `forgeCoreModule` | `create`, `doctor`, `upgrade`, `scaffold`, `skill.validate`, `skill.list`, `profile.validate`, `agents.generate`, `docs.archive`, `public-surface.validate` |
+| `forgeRfcModule` | `rfc.list`, `rfc.validate`, `rfc.create`, `rfc.verification.emit`, `rfc.implement.stamp` |
+| `forgeAdrModule` | `adr.list`, `adr.create`, `adr.validate`, `adr.archive`, `adr.implement.stamp` |
+| `forgeNamingModule` | `naming.convention.lint` |
+| `forgeCompassModule` | `compass.inventory`, `compass.validate`, `compass.summary.trim` |
+| `forgeWorkflowModule` | `workflow.lint`, `workflow.list`, `workflow.amend.list` |
+| `forgeSpecModule` | `spec.validate`, `spec.status`, `spec.materialize`, `spec.live.merge` |
+| `forgeSessionModule` | `session.save`, `session.archive`, `session.validate`, `session.list`, `metrics.aggregate` |
+| `forgePluginModule` | `forge.plugin.validate`, `forge.plugin.discover` |
+| `forgeProgramModule` | `program.packet.validate`, `program.packet.seal`, `program.packet.lease`, `program.packet.complete` |
+
+## FORGE_SKILLS
+
+The `FORGE_SKILLS` export contains the full skill registry — all 37 skill definitions with their frontmatter.
+
+```ts
+import { FORGE_SKILLS } from "@warpgogol/forge";
+
+for (const skill of FORGE_SKILLS) {
+  console.log(skill.name, skill.description);
+}
+```

package/os/core/core.module.ts

@@ -26,6 +26,7 @@
   <item>Lockfile safety net: docs.archive post-loop refreshes pnpm-lock.yaml after mission workpiece moves.</item>
   <item>RFC-0877: forge.create --in-place required, --profile required, --name optional (derived from folder), strict empty-directory check (only .git/ tolerated).</item>
   <item>RFC-0940: register forge.autonomy.validate command enforcing FORGE-AUTONOMY-01 (no @warpgogol/werkstatt-engine imports outside os/werkstatt/).</item>
+  <item>RFC-1080: register forge.public-surface.validate command for README/package.json consistency checks (SURFACE-01..05).</item>
 </CHANGE_SUMMARY>
 */
 
@@ -67,6 +68,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
   const { runKnowledgeCompact } = await import("./handlers/knowledge-compact.ts");
   const { runPackageHealth } = await import("./handlers/package-health.ts");
   const { runForgeAutonomyValidate } = await import("./handlers/forge-autonomy-validate.ts");
+  const { runPublicSurfaceValidate } = await import("./handlers/public-surface.ts");
 
   const scaffoldWrapper = async (
     input: ForgeCommandInput,
@@ -731,6 +733,19 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
         flags: {},
         execute: runForgeAutonomyValidate,
       },
+      {
+        name: "forge.public-surface.validate",
+        description:
+          "Check consistency between README.md, package.json, and docs/ structure. " +
+          "Enforces SURFACE-01..05 rules: README length, Node version match, " +
+          "no .tgz in root, docs/ structure, required root files (RFC-1080).",
+        scope: "workspace",
+        supportsAllSites: false,
+        reads: ["README.md", "package.json", "docs/**"],
+        cacheable: false,
+        flags: {},
+        execute: runPublicSurfaceValidate,
+      },
       {
         name: "docs.archive",
         description:

package/os/core/handlers/public-surface.ts

@@ -0,0 +1,189 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.public-surface.validate — check consistency between README.md, package.json, and docs/ structure. Enforces SURFACE-01..05 rules from RFC-1080.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not modify files — read-only validation.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1080: initial public-surface consistency validator — README length, Node version match, .tgz absence, docs/ structure, required root files.</item>
+  <item>RFC-1080: add monorepo auto-detection — resolve packages/forge/ when run from monorepo root.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+
+export interface SurfaceCheck {
+  rule: string;
+  message: string;
+  status: "pass" | "warn" | "fail";
+}
+
+export interface PublicSurfaceResult {
+  command: "forge.public-surface.validate";
+  status: "pass" | "fail";
+  checks: SurfaceCheck[];
+}
+
+const REQUIRED_DOCS_FILES = [
+  "docs/getting-started.md",
+  "docs/concepts/why-forge.md",
+  "docs/reference/cli.md",
+];
+
+const REQUIRED_ROOT_FILES = ["CONTRIBUTING.md", "SECURITY.md", "CHANGELOG.md"];
+
+function readJsonFile(filePath: string): Record<string, unknown> | null {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function extractNodeMajorVersion(range: string): number | null {
+  const match = range.match(/(\d+)/);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+export async function runPublicSurfaceValidate(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<PublicSurfaceResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const checks: SurfaceCheck[] = [];
+
+  // Monorepo vs standalone resolution (RFC-1080):
+  // If packages/forge/ exists relative to workspaceRoot, use it (monorepo mode).
+  // Otherwise, use workspaceRoot directly (standalone extracted repo mode).
+  const forgePkgRoot = fs.existsSync(path.join(workspaceRoot, "packages", "forge"))
+    ? path.join(workspaceRoot, "packages", "forge")
+    : workspaceRoot;
+
+  const readmePath = path.join(forgePkgRoot, "README.md");
+  const packageJsonPath = path.join(forgePkgRoot, "package.json");
+
+  const readmeContent = fs.existsSync(readmePath) ? fs.readFileSync(readmePath, "utf8") : "";
+  const readmeLines = readmeContent.split("\n").length;
+
+  const pkg = readJsonFile(packageJsonPath);
+
+  // SURFACE-01: README length (warning)
+  checks.push({
+    rule: "SURFACE-01",
+    message: `README.md is ${readmeLines} lines (${readmeLines <= 300 ? "under 300" : "over 300"})`,
+    status: readmeLines <= 300 ? "pass" : "warn",
+  });
+
+  // SURFACE-02: Node version consistency (error)
+  if (pkg) {
+    const engines = pkg["engines"] as Record<string, string> | undefined;
+    const nodeRange = engines?.["node"];
+    const pkgMajor = nodeRange ? extractNodeMajorVersion(nodeRange) : null;
+
+    if (pkgMajor !== null) {
+      const readmeNodeMatch = readmeContent.match(/Node(?:\.js)?\s+v?(\d+)/gi);
+      const readmeNodeVersions = readmeNodeMatch
+        ? readmeNodeMatch.map((m) => parseInt(m.match(/(\d+)/)![1], 10))
+        : [];
+
+      const mismatched = readmeNodeVersions.filter((v) => v !== pkgMajor);
+      checks.push({
+        rule: "SURFACE-02",
+        message:
+          mismatched.length === 0
+            ? `Node version consistent: ${nodeRange}`
+            : `README references Node ${mismatched.join(", ")} but package.json requires ${nodeRange}`,
+        status: mismatched.length === 0 ? "pass" : "fail",
+      });
+    } else {
+      checks.push({
+        rule: "SURFACE-02",
+        message: "package.json missing engines.node",
+        status: "fail",
+      });
+    }
+  } else {
+    checks.push({
+      rule: "SURFACE-02",
+      message: "package.json not found",
+      status: "fail",
+    });
+  }
+
+  // SURFACE-03: No .tgz files in root (error)
+  const tgzFiles = fs.readdirSync(forgePkgRoot).filter((f) => f.endsWith(".tgz"));
+  checks.push({
+    rule: "SURFACE-03",
+    message:
+      tgzFiles.length === 0
+        ? "No .tgz files in root"
+        : `Found ${tgzFiles.length} .tgz file(s): ${tgzFiles.join(", ")}`,
+    status: tgzFiles.length === 0 ? "pass" : "fail",
+  });
+
+  // SURFACE-04: docs/ directory with required files (error)
+  const missingDocs = REQUIRED_DOCS_FILES.filter((f) => !fs.existsSync(path.join(forgePkgRoot, f)));
+  checks.push({
+    rule: "SURFACE-04",
+    message:
+      missingDocs.length === 0
+        ? "docs/ directory exists with required files"
+        : `Missing docs files: ${missingDocs.join(", ")}`,
+    status: missingDocs.length === 0 ? "pass" : "fail",
+  });
+
+  // SURFACE-05: Required root files (warning)
+  const missingRoot = REQUIRED_ROOT_FILES.filter((f) => !fs.existsSync(path.join(forgePkgRoot, f)));
+  checks.push({
+    rule: "SURFACE-05",
+    message:
+      missingRoot.length === 0
+        ? "Required root files present (CONTRIBUTING.md, SECURITY.md, CHANGELOG.md)"
+        : `Missing root files: ${missingRoot.join(", ")}`,
+    status: missingRoot.length === 0 ? "pass" : "warn",
+  });
+
+  const hasFails = checks.some((c) => c.status === "fail");
+  const status: "pass" | "fail" = hasFails ? "fail" : "pass";
+
+  if (outputFormat === "pretty") {
+    logger.section("Forge Public Surface Validate");
+    for (const check of checks) {
+      const icon = check.status === "pass" ? "✓" : check.status === "warn" ? "⚠" : "✖";
+      const fn =
+        check.status === "pass"
+          ? logger.success
+          : check.status === "warn"
+            ? logger.warn
+            : logger.error;
+      fn(`${icon} [${check.rule}] ${check.message}`);
+    }
+    if (status === "pass") {
+      logger.success("All public surface checks passed.");
+    } else {
+      logger.error("Some public surface checks failed.");
+    }
+  }
+
+  return {
+    data: {
+      command: "forge.public-surface.validate",
+      status,
+      checks,
+    },
+    exitCode: hasFails ? 1 : 0,
+    summary:
+      status === "pass"
+        ? "forge.public-surface.validate: all checks passed"
+        : `forge.public-surface.validate: ${checks.filter((c) => c.status === "fail").length} fail(s), ${checks.filter((c) => c.status === "warn").length} warn(s)`,
+  };
+}

package/os/rfc/handlers/validate-rules.ts

@@ -225,7 +225,6 @@ export function evaluateAcceptanceCriteria(body: string): AcceptanceCriteriaEval
     .split("\n")
     .filter((line) => /^- \[ \]/.test(line))
     .map((line) => line.trim());
-  const totalUnchecked = uncheckedLines.length;
 
   const checkedLines = section.split("\n").filter((line) => /^- \[x\]/.test(line));
   const checkedWithoutEvidence: string[] = [];

package/os/rfc/verification-refresh.test.ts

@@ -6,6 +6,7 @@ import os from "node:os";
 import { stringify as yamlStringify } from "yaml";
 
 import { runRfcVerificationRefresh } from "./verification-refresh.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../../src/types.ts";
 
 const { mockRunProbe, mockCaptureGitContext, mockGetKernelVersion } = vi.hoisted(() => ({
   mockRunProbe: vi.fn(),
@@ -26,11 +27,11 @@ vi.mock("./verification-evidence.ts", async (importOriginal) => {
   };
 });
 
-const RFC_FRONTMATTER = (id: string, status: string, probes: unknown[] = []) => {
+const RFC_FRONTMATTER = (id: string, status: string, probes: Record<string, unknown>[] = []) => {
   const probeYaml = probes
     .map(
       (p) =>
-        `  - probe: ${(p as any).probe}\n    path: ${(p as any).path ?? ""}\n    criterion: ${(p as any).criterion ?? ""}`,
+        `  - probe: ${p.probe}\n    path: ${p.path ?? ""}\n    criterion: ${p.criterion ?? ""}`,
     )
     .join("\n");
   return `---\nid: ${id}\ntitle: "Test ${id}"\nstatus: ${status}\nkind: command\nscope: workspace\nowners:\n  - architecture\ncreatedAt: 2026-01-01\nupdatedAt: 2026-01-01\nacceptance:\n${probeYaml}\n---\n\n# ${id}\n## Context\nTest.\n`;
@@ -134,8 +135,8 @@ describe("rfc.verification.refresh — AC-1: single-RFC refresh", () => {
       mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
 
       const result = await runRfcVerificationRefresh(
-        { flags: { id: "RFC-0100" } } as any,
-        makeContext(workspaceRoot) as any,
+        { flags: { id: "RFC-0100" } } as unknown as ForgeCommandInput,
+        makeContext(workspaceRoot) as unknown as ForgeRuntimeContext,
       );
 
       expect(result.data!.refreshed).toHaveLength(1);
@@ -175,8 +176,8 @@ describe("rfc.verification.refresh — AC-2: --all mode", () => {
       mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
 
       const result = await runRfcVerificationRefresh(
-        { flags: { all: true } } as any,
-        makeContext(workspaceRoot) as any,
+        { flags: { all: true } } as unknown as ForgeCommandInput,
+        makeContext(workspaceRoot) as unknown as ForgeRuntimeContext,
       );
 
       expect(result.data!.refreshed).toHaveLength(2);
@@ -200,8 +201,8 @@ describe("rfc.verification.refresh — AC-3: probe failure still writes envelope
       mockRunProbe.mockResolvedValue({ probe: PROBE, ok: false, detail: "does not exist" });
 
       const result = await runRfcVerificationRefresh(
-        { flags: { id: "RFC-0100" } } as any,
-        makeContext(workspaceRoot) as any,
+        { flags: { id: "RFC-0100" } } as unknown as ForgeCommandInput,
+        makeContext(workspaceRoot) as unknown as ForgeRuntimeContext,
       );
 
       expect(result.data!.refreshed).toHaveLength(1);
@@ -236,8 +237,8 @@ describe("rfc.verification.refresh — AC-4: --dry-run does not write files", ()
       mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
 
       const result = await runRfcVerificationRefresh(
-        { flags: { id: "RFC-0100", "dry-run": true } } as any,
-        makeContext(workspaceRoot) as any,
+        { flags: { id: "RFC-0100", "dry-run": true } } as unknown as ForgeCommandInput,
+        makeContext(workspaceRoot) as unknown as ForgeRuntimeContext,
       );
 
       expect(result.data!.refreshed).toHaveLength(1);
@@ -270,8 +271,8 @@ describe("rfc.verification.refresh — AC-5: no evidence envelope", () => {
       mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
 
       const result = await runRfcVerificationRefresh(
-        { flags: { id: "RFC-0100" } } as any,
-        makeContext(workspaceRoot) as any,
+        { flags: { id: "RFC-0100" } } as unknown as ForgeCommandInput,
+        makeContext(workspaceRoot) as unknown as ForgeRuntimeContext,
       );
 
       expect(result.data!.refreshed).toHaveLength(0);
@@ -296,8 +297,8 @@ describe("rfc.verification.refresh — AC-6: emittedAt preservation", () => {
       mockRunProbe.mockResolvedValue({ probe: PROBE, ok: true, detail: "exists" });
 
       await runRfcVerificationRefresh(
-        { flags: { id: "RFC-0100" } } as any,
-        makeContext(workspaceRoot) as any,
+        { flags: { id: "RFC-0100" } } as unknown as ForgeCommandInput,
+        makeContext(workspaceRoot) as unknown as ForgeRuntimeContext,
       );
 
       const envelopePath = path.join(

package/os/rfc/verification-refresh.ts

@@ -30,7 +30,6 @@ import { stringify as yamlStringify } from "yaml";
 import {
   captureGitContext,
   getKernelVersion,
-  byteHashHex,
   VERIFICATION_DIR,
   buildEvidenceEnvelope,
 } from "./verification-evidence.ts";
@@ -49,10 +48,6 @@ import type {
   ForgeRuntimeContext,
 } from "../../src/types.ts";
 
-function normalizeProbes(probes: AcceptanceProbe[]): string {
-  return JSON.stringify(probes, Object.keys(probes[0] ?? {}).sort());
-}
-
 export async function runRfcVerificationRefresh(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
@@ -74,8 +69,7 @@ export async function runRfcVerificationRefresh(
         summary: { total: 0, passed: 0, failed: 0, skipped: 0 },
       },
       exitCode: 0,
-      summary:
-        "rfc.verification.refresh: pass --id <rfc-id> or --all to select target RFC(s)",
+      summary: "rfc.verification.refresh: pass --id <rfc-id> or --all to select target RFC(s)",
     };
   }
 

package/os/session/handlers/metrics-session.ts

@@ -17,13 +17,19 @@ docs/metrics/sessions/<session-id>.metrics.yaml via writeFileAtomic.
 </CHANGE_SUMMARY>
 */
 
-import { readFile, readdir, mkdir } from "node:fs/promises";
+import { readdir, mkdir } from "node:fs/promises";
 import { join, dirname } from "node:path";
 
 import { writeFileAtomic } from "../../../src/utils/fs-atomic.ts";
 import { stringify as yamlStringify } from "yaml";
 
-import { METRICS_DIR, type SessionMetrics, type SessionSkillInvocation, type SessionDocumentRef, type InsightSummary } from "../types.ts";
+import {
+  METRICS_DIR,
+  type SessionMetrics,
+  type SessionSkillInvocation,
+  type SessionDocumentRef,
+  type InsightSummary,
+} from "../types.ts";
 import type { AtifMessage } from "../atif-parser.ts";
 
 // ─── Skill name extraction ───────────────────────────────────────────────────
@@ -176,7 +182,7 @@ export async function generateSessionMetrics(
     relatedRfcs?: string[];
     commits?: string[];
   },
-  logger: { warn: (msg: string) => void },
+  _logger: { warn: (msg: string) => void },
 ): Promise<string> {
   const skills = extractSkillInvocations(messages);
   const documents = await extractDocumentRefs(workspaceRoot, sessionFrontmatter.relatedRfcs ?? []);
@@ -196,12 +202,7 @@ export async function generateSessionMetrics(
   };
 
   const yamlContent = yamlStringify(metrics, { lineWidth: 120 });
-  const metricsFilePath = join(
-    workspaceRoot,
-    METRICS_DIR,
-    "sessions",
-    `${sessionId}.metrics.yaml`,
-  );
+  const metricsFilePath = join(workspaceRoot, METRICS_DIR, "sessions", `${sessionId}.metrics.yaml`);
   await mkdir(dirname(metricsFilePath), { recursive: true });
   await writeFileAtomic(metricsFilePath, yamlContent);
 

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "@warpgogol/forge",
-  "version": "4.1.6",
+  "version": "4.2.1",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
-  "description": "Framework for documenting and implementing ideas — RFC/ADR governance, skills, and project bootstrapping.",
+  "description": "Repository-native governance for AI-assisted software development — project contracts, RFCs, ADRs, agent skills and deterministic validation.",
   "keywords": [
+    "ai",
+    "agent",
     "rfc",
     "adr",
     "governance",
     "skills",
-    "ai-agent",
-    "documentation",
-    "framework"
+    "validation",
+    "project-contract",
+    "ai-assisted",
+    "documentation"
   ],
-  "homepage": "https://warpgogol.com",
+  "homepage": "https://forge.warpgogol.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/syrokomskyi/forge.git"
@@ -154,9 +157,14 @@
     "src/",
     "src/onboarding/templates/",
     "os/",
+    "docs/",
     "AGENTS.md",
     "README.md",
-    "LICENSE"
+    "README.uk.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "pnpm exec tsc -p tsconfig.json",