@warpgogol/forge 5.1.3 → 5.2.3

package/os/compass/handlers/tests/compass-ledger-scope.test.ts

@@ -0,0 +1,124 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>
+    RFC-1139 AC-5: compass.audit.baseline must not seed ledger entries for
+    paths under missions/ or gitignored roots — the tracked ledger only
+    accumulates entries for paths that can be audited long-term.
+  </purpose>
+</MODULE_CONTRACT>
+*/
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, writeFile, rm, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { parse as yamlParse } from "yaml";
+import { runCompassAuditBaseline } from "../compass-audit-handler.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../../../../src/types.ts";
+
+const execFileAsync = promisify(execFile);
+
+const logger = {
+  section() {},
+  info() {},
+  warn() {},
+  error() {},
+  success() {},
+  getEvents() {
+    return [];
+  },
+};
+
+function makeContext(workspaceRoot: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    site: undefined,
+    siteExplicit: false,
+    logger: logger as never,
+    dryRun: false,
+    outputFormat: "json",
+    io: {} as never,
+    actualState: undefined as never,
+    fileIntents: [],
+  } as unknown as ForgeRuntimeContext;
+}
+
+function makeInput(flags: Record<string, unknown> = {}): ForgeCommandInput {
+  return { argv: [], flags } as unknown as ForgeCommandInput;
+}
+
+interface LedgerEntry {
+  path: string;
+}
+
+describe("compass.audit.baseline — RFC-1139 ledger scope", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "compass-ledger-"));
+    // Authored source file (plain .ts, no generated marker → authored entry)
+    await mkdir(join(root, "packages", "foo"), { recursive: true });
+    await writeFile(join(root, "packages", "foo", "index.ts"), "export const x = 1;\n", "utf8");
+    // Mission workpiece file — would be authored but must be excluded
+    await mkdir(join(root, "missions", "acme-m000001", "workpiece", "src"), {
+      recursive: true,
+    });
+    await writeFile(
+      join(root, "missions", "acme-m000001", "workpiece", "src", "local.ts"),
+      "export const y = 2;\n",
+      "utf8",
+    );
+    // Gitignored generated dir — excluded via check-ignore
+    await mkdir(join(root, "dist"), { recursive: true });
+    await writeFile(join(root, "dist", "bundle.ts"), "export const z = 3;\n", "utf8");
+    await writeFile(join(root, ".gitignore"), "dist/\nmissions/\n", "utf8");
+    // Git repo for getRevisionByPath + check-ignore
+    await execFileAsync("git", ["init"], { cwd: root });
+    await execFileAsync("git", ["config", "user.email", "test@test.com"], { cwd: root });
+    await execFileAsync("git", ["config", "user.name", "Test"], { cwd: root });
+    await execFileAsync("git", ["add", "."], { cwd: root });
+    await execFileAsync("git", ["commit", "-m", "init"], { cwd: root });
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("AC-5: baseline seeds no missions/ or gitignored ledger entries", async () => {
+    const result = await runCompassAuditBaseline(makeInput(), makeContext(root));
+    expect(result.exitCode).toBe(0);
+
+    const ledgerRaw = await readFile(
+      join(root, "docs", "compass-audit-ledger.generated.yaml"),
+      "utf8",
+    );
+    const ledger = yamlParse(ledgerRaw) as { entries: LedgerEntry[] };
+    const paths = ledger.entries.map((e) => e.path);
+
+    expect(paths.some((p) => p.startsWith("missions/"))).toBe(false);
+    expect(paths.some((p) => p.startsWith("dist/"))).toBe(false);
+    expect(paths).toContain("packages/foo/index.ts");
+  });
+
+  it("AC-5: pre-existing missions/ entries are pruned on next baseline", async () => {
+    // Seed a ledger with a stale missions/ entry
+    await mkdir(join(root, "docs"), { recursive: true });
+    await writeFile(
+      join(root, "docs", "compass-audit-ledger.generated.yaml"),
+      `entries:\n  - path: missions/acme-m000001/workpiece/src/local.ts\n    entityId: ""\n    auditedRevision: abc\n    auditedHash: def\n    auditedAt: "2026-01-01T00:00:00Z"\n    verdict: baseline\n    agent: system:baseline\n`,
+      "utf8",
+    );
+
+    const result = await runCompassAuditBaseline(makeInput(), makeContext(root));
+    expect(result.exitCode).toBe(0);
+
+    const ledgerRaw = await readFile(
+      join(root, "docs", "compass-audit-ledger.generated.yaml"),
+      "utf8",
+    );
+    const ledger = yamlParse(ledgerRaw) as { entries: LedgerEntry[] };
+    expect(ledger.entries.some((e) => e.path.startsWith("missions/"))).toBe(false);
+  });
+});

package/os/core/core.module.ts

@@ -305,7 +305,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       {
         name: "forge.scaffold",
         description:
-          "Create a working pnpm + Turborepo monorepo from a stack profile in an empty directory.",
+          "Create a working pnpm + Turborepo monorepo from a stack profile in an empty directory. Required flags: `--profile`, `--name`.",
         scope: "workspace",
         supportsAllSites: false,
         flags: {

package/os/mission/handlers/archive.test.ts

@@ -572,4 +572,53 @@ describe("mission.archive", () => {
     expect(data.skipped).toHaveLength(1);
     expect(data.skipped[0].reason).toContain("use --clean-orphans");
   });
+
+  test("RFC-1138 AC-2: git add -A skipped when archive target is gitignored", async () => {
+    execSyncMock.mockReset();
+    execSyncMock.mockImplementation((cmd: string) => {
+      if (cmd.startsWith("pnpm install")) return "";
+      if (cmd.startsWith("git status --porcelain pnpm-lock.yaml")) return "M pnpm-lock.yaml";
+      // git check-ignore exits 0 → path is ignored (missions/ is gitignored)
+      if (cmd.startsWith("git check-ignore")) return "";
+      return "";
+    });
+    await writeMissionManifest(missionsDir, "test-r1138-01", "closed");
+
+    await runMissionArchive(makeInput(), makeContext(tmpDir));
+
+    const checkIgnoreCall = execSyncMock.mock.calls.find(
+      (c) => typeof c[0] === "string" && c[0].startsWith("git check-ignore"),
+    );
+    expect(checkIgnoreCall).toBeDefined();
+
+    const addArchiveCall = execSyncMock.mock.calls.find(
+      (c) => typeof c[0] === "string" && c[0].startsWith("git add -A"),
+    );
+    expect(addArchiveCall).toBeUndefined();
+
+    // Lockfile itself is still staged + committed
+    const lockfileAdd = execSyncMock.mock.calls.find(
+      (c) => typeof c[0] === "string" && c[0] === "git add pnpm-lock.yaml",
+    );
+    expect(lockfileAdd).toBeDefined();
+  });
+
+  test("RFC-1138 AC-2: git add -A still runs when archive target is NOT gitignored", async () => {
+    execSyncMock.mockReset();
+    execSyncMock.mockImplementation((cmd: string) => {
+      if (cmd.startsWith("pnpm install")) return "";
+      if (cmd.startsWith("git status --porcelain pnpm-lock.yaml")) return "M pnpm-lock.yaml";
+      // git check-ignore exits 1 → not ignored → execSync throws
+      if (cmd.startsWith("git check-ignore")) throw new Error("exit 1");
+      return "";
+    });
+    await writeMissionManifest(missionsDir, "test-r1138-02", "closed");
+
+    await runMissionArchive(makeInput(), makeContext(tmpDir));
+
+    const addArchiveCall = execSyncMock.mock.calls.find(
+      (c) => typeof c[0] === "string" && c[0].startsWith("git add -A"),
+    );
+    expect(addArchiveCall).toBeDefined();
+  });
 });

package/os/mission/handlers/archive.ts

@@ -13,7 +13,6 @@ archive subdirectories back to missions/.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0733: add pinned-files pre-check — skip pinned mission directories with warning instead of moving them.</item>
   <item>RFC-0804: auto-refresh pnpm-lock.yaml after directory moves.</item>
   <item>RFC-0982: fallback state detection for orphaned workpiece dirs (no mission.yaml) via .closed marker and cache-only heuristic; --clean-orphans flag; improved skip reasons.</item>
   <item>RFC-1097: step 6 — compass.migrate codemod run
@@ -22,7 +21,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-0573, RFC-0801</history>
+  <item>RFC-1138: pipeline hygiene — module-scoped exempt entries, archive gitignore guard, dns upsert to deploy phases, promote auto-sync, rfc.create claim protocol, siteHasRuntime filter</item>
+  <history>RFC-0573, RFC-0733, RFC-0801</history>
 </CHANGE_SUMMARY>
 */
 
@@ -520,10 +520,25 @@ export async function runMissionArchive(
           stdio: ["pipe", "pipe", "pipe"],
         });
         for (const m of moved) {
-          execSync(`git add -A ${JSON.stringify(m.to)}`, {
-            cwd: workspaceRoot,
-            stdio: ["pipe", "pipe", "pipe"],
-          });
+          // RFC-1138: missions/ is gitignored — `git add` on the archive path is
+          // structurally guaranteed to fail. Skip staging when the target is
+          // ignored (git check-ignore exits 0 = ignored, 1 = not ignored).
+          let targetIgnored = false;
+          try {
+            execSync(`git check-ignore -q ${JSON.stringify(m.to)}`, {
+              cwd: workspaceRoot,
+              stdio: ["pipe", "pipe", "pipe"],
+            });
+            targetIgnored = true;
+          } catch {
+            targetIgnored = false;
+          }
+          if (!targetIgnored) {
+            execSync(`git add -A ${JSON.stringify(m.to)}`, {
+              cwd: workspaceRoot,
+              stdio: ["pipe", "pipe", "pipe"],
+            });
+          }
           if (existsSync(m.from)) continue;
           execSync(`git rm -r --cached --ignore-unmatch ${JSON.stringify(m.from)}`, {
             cwd: workspaceRoot,

package/os/program/lease.ts

@@ -38,7 +38,7 @@ export function leasePath(workspaceRoot: string, program: string, packetId: stri
  * Generate a random opaque lease token (32 bytes hex).
  */
 export function generateLeaseToken(): string {
-  return randomBytes(32).toString("hex");
+  return Array.from(randomBytes(32), (b) => b.toString(16).padStart(2, "0")).join("");
 }
 
 /**

package/os/queue/handlers/queue-validate.ts

@@ -0,0 +1,83 @@
+/*
+<MODULE_CONTRACT>
+<purpose>queue.validate command handler (RFC-1140) — validates a queue
+manifest and reports derived per-item pipeline status plus the next
+actionable item. Read-only; the orchestrator runs this before a queued batch.</purpose>
+<non-goals>
+  <item>Do not execute the queue — this command validates and previews only.</item>
+  <item>Do not mutate any files.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1140: initial queue.validate handler.</item>
+  <item>RFC-1140: steps 1-4 — shared resolver, queue module, registration
+
+Extract pipeline-status derivation into packages/forge/src/pipeline-status.ts, refactor rfc.pipeline.status onto it, add os/queue module with queue.validate command, register in WORKSHOP_MODULE_MAP.forge + bin/cli.ts + package.json exports.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { deriveQueueReport } from "../../../src/pipeline-status.ts";
+import { loadQueueManifest } from "../manifest.ts";
+import type { QueueValidateResult } from "../types.ts";
+
+export async function runQueueValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<QueueValidateResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+
+  const file = input.flags["file"] as string | undefined;
+  if (!file) {
+    throw new Error("queue.validate requires --file <path-to-manifest.yaml>");
+  }
+
+  const { manifest, errors, warnings } = await loadQueueManifest(workspaceRoot, file);
+
+  const report =
+    errors.length === 0
+      ? await deriveQueueReport(
+          workspaceRoot,
+          manifest.items.map((i) => i.id),
+        )
+      : { items: [], next: null };
+
+  const status = errors.length === 0 ? "pass" : "fail";
+
+  if (outputFormat === "pretty") {
+    logger.section(`Queue: ${manifest.id || file}`);
+    for (const item of report.items) {
+      const step = item.pipelineStep ? ` (${item.pipelineStep})` : "";
+      logger.info(`  ${item.id}: ${item.status}${step}`);
+    }
+    logger.info(`next: ${report.next ?? "—"}`);
+    for (const w of warnings) {
+      logger.warn(`  ${w.ruleId}: ${w.message}`);
+    }
+    for (const e of errors) {
+      logger.error(`  ${e.ruleId}: ${e.message}`);
+    }
+  }
+
+  return {
+    data: {
+      command: "queue.validate",
+      status,
+      queue: manifest.id,
+      file,
+      items: report.items,
+      next: report.next,
+      errors,
+      warnings,
+    },
+    summary:
+      status === "pass"
+        ? `Queue "${manifest.id}": ${report.items.length} item(s), next: ${report.next ?? "none"}`
+        : `Queue manifest invalid: ${errors.length} error(s)`,
+    exitCode: status === "pass" ? 0 : 1,
+  };
+}

package/os/queue/index.ts

@@ -0,0 +1,19 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for the forge queue module (RFC-1140).</purpose>
+<non-goals>
+  <item>Do not add logic here — re-exports only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1140: initial barrel export.</item>
+  <item>RFC-1140: steps 1-4 — shared resolver, queue module, registration
+
+Extract pipeline-status derivation into packages/forge/src/pipeline-status.ts, refactor rfc.pipeline.status onto it, add os/queue module with queue.validate command, register in WORKSHOP_MODULE_MAP.forge + bin/cli.ts + package.json exports.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { createForgeQueueModule } from "./queue.module.ts";
+export { loadQueueManifest } from "./manifest.ts";
+export { queueManifestSchema, QUEUE_ITEM_ID_PATTERN } from "./types.ts";
+export type { QueueManifest, QueueValidateResult } from "./types.ts";

package/os/queue/manifest.ts

@@ -0,0 +1,183 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Queue manifest loading and validation (RFC-1140) — YAML parse, zod
+schema, id↔filename stem check, item id pattern, document resolution across
+active and archive dirs, duplicate detection, and dependsOn order warnings.</purpose>
+<non-goals>
+  <item>Do not derive item status — that is src/pipeline-status.ts.</item>
+  <item>Do not mutate the manifest file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1140: initial manifest loader and validator.</item>
+  <item>RFC-1140: steps 1-4 — shared resolver, queue module, registration
+
+Extract pipeline-status derivation into packages/forge/src/pipeline-status.ts, refactor rfc.pipeline.status onto it, add os/queue module with queue.validate command, register in WORKSHOP_MODULE_MAP.forge + bin/cli.ts + package.json exports.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+
+import type { Diagnostic } from "../../src/types.ts";
+import { resolveDocument } from "../../src/pipeline-status.ts";
+import { QUEUE_ITEM_ID_PATTERN, queueManifestSchema } from "./types.ts";
+import type { QueueManifest } from "./types.ts";
+
+export interface LoadedQueueManifest {
+  manifest: QueueManifest;
+  errors: Diagnostic[];
+  warnings: Diagnostic[];
+}
+
+function diag(
+  ruleId: string,
+  severity: "error" | "warning",
+  message: string,
+  file?: string,
+): Diagnostic {
+  return { ruleId, severity, message, file };
+}
+
+/**
+ * Load and validate a queue manifest. Blocking errors: unreadable/invalid
+ * YAML, schema violations, id↔filename mismatch, malformed or unresolvable
+ * item ids, duplicates. Non-blocking: dependsOn order violations.
+ */
+export async function loadQueueManifest(
+  workspaceRoot: string,
+  filePath: string,
+): Promise<LoadedQueueManifest> {
+  const errors: Diagnostic[] = [];
+  const warnings: Diagnostic[] = [];
+  const absolutePath = path.isAbsolute(filePath)
+    ? filePath
+    : path.join(workspaceRoot, filePath);
+  const displayPath = path.isAbsolute(filePath)
+    ? path.relative(workspaceRoot, filePath)
+    : filePath;
+
+  let source: string;
+  try {
+    source = await fs.readFile(absolutePath, "utf-8");
+  } catch (e) {
+    errors.push(
+      diag(
+        "QUEUE-01",
+        "error",
+        `Cannot read queue manifest: ${e instanceof Error ? e.message : String(e)}`,
+        displayPath,
+      ),
+    );
+    return { manifest: { id: "", createdAt: "", items: [] }, errors, warnings };
+  }
+
+  let raw: unknown;
+  try {
+    raw = YAML.parse(source);
+  } catch (e) {
+    errors.push(
+      diag(
+        "QUEUE-01",
+        "error",
+        `YAML parse error: ${e instanceof Error ? e.message : String(e)}`,
+        displayPath,
+      ),
+    );
+    return { manifest: { id: "", createdAt: "", items: [] }, errors, warnings };
+  }
+
+  const parsed = queueManifestSchema.safeParse(raw);
+  if (!parsed.success) {
+    for (const issue of parsed.error.issues) {
+      errors.push(
+        diag(
+          "QUEUE-01",
+          "error",
+          `Manifest schema violation at ${issue.path.join(".") || "<root>"}: ${issue.message}`,
+          displayPath,
+        ),
+      );
+    }
+    return { manifest: { id: "", createdAt: "", items: [] }, errors, warnings };
+  }
+
+  const manifest = parsed.data;
+
+  // QUEUE-02: manifest id must equal the filename stem.
+  const stem = path.basename(absolutePath).replace(/\.(ya?ml)$/i, "");
+  if (manifest.id !== stem) {
+    errors.push(
+      diag(
+        "QUEUE-02",
+        "error",
+        `Manifest id "${manifest.id}" does not match filename stem "${stem}"`,
+        displayPath,
+      ),
+    );
+  }
+
+  // QUEUE-03/04/05: item id pattern, resolution, duplicates.
+  const seen = new Set<string>();
+  const resolvedDependsOn = new Map<string, string[]>();
+  for (const item of manifest.items) {
+    const id = item.id.trim();
+    if (!QUEUE_ITEM_ID_PATTERN.test(id)) {
+      errors.push(
+        diag("QUEUE-03", "error", `Item id "${item.id}" does not match ^(RFC|ADR)-\\d{4}$`, displayPath),
+      );
+      continue;
+    }
+    const upper = id.toUpperCase();
+    if (seen.has(upper)) {
+      errors.push(diag("QUEUE-05", "error", `Duplicate item id "${upper}"`, displayPath));
+      continue;
+    }
+    seen.add(upper);
+
+    const doc = await resolveDocument(workspaceRoot, upper);
+    if (!doc) {
+      errors.push(
+        diag(
+          "QUEUE-04",
+          "error",
+          `Item "${upper}" does not resolve to a document in docs/rfcs/ or docs/adrs/ (incl. archive)`,
+          displayPath,
+        ),
+      );
+      continue;
+    }
+
+    const dependsOn = doc.frontmatter["dependsOn"];
+    if (Array.isArray(dependsOn)) {
+      resolvedDependsOn.set(
+        upper,
+        dependsOn.map((d) => String(d).toUpperCase()),
+      );
+    }
+  }
+
+  // QUEUE-06: dependsOn order — an item must not precede its in-queue dependency.
+  const order = new Map<string, number>();
+  manifest.items.forEach((item, index) => order.set(item.id.trim().toUpperCase(), index));
+  for (const [itemId, deps] of resolvedDependsOn) {
+    const itemIndex = order.get(itemId);
+    if (itemIndex === undefined) continue;
+    for (const dep of deps) {
+      const depIndex = order.get(dep);
+      if (depIndex !== undefined && depIndex > itemIndex) {
+        warnings.push(
+          diag(
+            "QUEUE-06",
+            "warning",
+            `Item "${itemId}" (position ${itemIndex + 1}) precedes its dependsOn dependency "${dep}" (position ${depIndex + 1})`,
+            displayPath,
+          ),
+        );
+      }
+    }
+  }
+
+  return { manifest, errors, warnings };
+}