@warpgogol/forge 5.1.3 → 5.2.3

package/src/pipeline-status.ts

@@ -0,0 +1,319 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Shared pipeline-status resolver (RFC-1140) — derives per-document
+pipeline progress (audit, enhance, plan, implement) from document frontmatter
+and pipeline artifacts. Single source of truth consumed by rfc.pipeline.status,
+queue.validate, and the orchestrator's resume detection. Portable layer: no
+os/ or kernel imports.</purpose>
+<non-goals>
+  <item>Do not validate RFC/ADR content — use rfc.validate / adr.validate.</item>
+  <item>Do not mutate any files — derivation is read-only.</item>
+  <item>Do not store progress state — status is derived at read time, never persisted.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1140: initial shared resolver — artifact conventions (audit-*.md,
+  plan-*.md, enhancedAt, implementedAt) extracted from
+  os/rfc/handlers/pipeline-status.ts; QueueItemStatus derivation matrix added
+  for queue.validate.</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>
+  <item>RFC-1140: step 6 — cover shared resolver and queue.validate
+
+Add pipeline-status.test.ts (derivation matrix, order, next selection, ADR, skipped) and queue-validate.test.ts (schema errors, unknown/dup ids, id-filename mismatch, empty items, dependsOn warning, JSON shape). Fix queue derivation: pipelineStep is the stage after the last completed stage, not first incomplete — handles non-contiguous artifacts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+
+// ---------------------------------------------------------------------------
+// Pipeline stages (shared with rfc.pipeline.status)
+// ---------------------------------------------------------------------------
+
+export type PipelineStage = "audit" | "enhance" | "plan" | "implement";
+
+export interface RfcPipelineStageInfo {
+  stage: PipelineStage;
+  done: boolean;
+  /** File or marker that confirms completion, when applicable. */
+  evidence?: string;
+}
+
+export const TERMINAL_STATUSES: ReadonlySet<string> = new Set([
+  "implemented",
+  "rejected",
+  "superseded",
+]);
+
+// ---------------------------------------------------------------------------
+// Minimal frontmatter parsing (self-contained — src/ must not import os/)
+// ---------------------------------------------------------------------------
+
+export interface ParsedDocument {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+export function parseFrontmatter(source: string): ParsedDocument {
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: source };
+  }
+  return {
+    frontmatter: (YAML.parse(match[1]!) ?? {}) as Record<string, unknown>,
+    body: match[2] ?? "",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Artifact finders — the canonical conventions
+// ---------------------------------------------------------------------------
+
+export async function findAuditFile(
+  workspaceRoot: string,
+  docId: string,
+): Promise<string | undefined> {
+  const auditsDir = path.join(workspaceRoot, "docs/audits");
+  try {
+    const entries = await fs.readdir(auditsDir);
+    const prefix = `audit-${docId.toLowerCase()}`;
+    const match = entries.find((e) => e.toLowerCase().startsWith(prefix) && e.endsWith(".md"));
+    return match ? path.join("docs/audits", match) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function findPlanFile(
+  workspaceRoot: string,
+  docId: string,
+): Promise<string | undefined> {
+  const plansDir = path.join(workspaceRoot, "docs/plans");
+  try {
+    const entries = await fs.readdir(plansDir);
+    const prefix = `plan-${docId.toLowerCase()}`;
+    const match = entries.find((e) => e.toLowerCase().startsWith(prefix) && e.endsWith(".md"));
+    return match ? path.join("docs/plans", match) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Document resolution — active dir + archive (implemented docs may be archived)
+// ---------------------------------------------------------------------------
+
+export type QueueDocumentKind = "rfc" | "adr";
+
+export interface ResolvedDocument {
+  id: string;
+  kind: QueueDocumentKind;
+  /** Workspace-relative path to the document file. */
+  file: string;
+  frontmatter: Record<string, unknown>;
+}
+
+const DOC_ID_PATTERN = /^(RFC|ADR)-\d{4}$/i;
+
+async function scanForDocument(
+  dirPath: string,
+  relativePrefix: string,
+  idLower: string,
+): Promise<string | undefined> {
+  let entries;
+  try {
+    entries = await fs.readdir(dirPath, { withFileTypes: true });
+  } catch {
+    return undefined;
+  }
+  for (const entry of entries) {
+    const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      const found = await scanForDocument(path.join(dirPath, entry.name), relativePath, idLower);
+      if (found) return found;
+    } else if (
+      entry.isFile() &&
+      entry.name.endsWith(".md") &&
+      entry.name.toLowerCase().startsWith(idLower)
+    ) {
+      return relativePath;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Resolve an RFC-XXXX or ADR-XXXX id to its document file and parsed
+ * frontmatter. Scans the active dir and archive subdirectories recursively.
+ * Returns undefined when the id is malformed or no file matches.
+ */
+export async function resolveDocument(
+  workspaceRoot: string,
+  docId: string,
+): Promise<ResolvedDocument | undefined> {
+  const idMatch = DOC_ID_PATTERN.exec(docId.trim());
+  if (!idMatch) return undefined;
+  const kind: QueueDocumentKind = idMatch[1]!.toUpperCase() === "ADR" ? "adr" : "rfc";
+  const baseDir = kind === "adr" ? "docs/adrs" : "docs/rfcs";
+  const idLower = docId.toLowerCase();
+
+  const found = await scanForDocument(path.join(workspaceRoot, baseDir), "", idLower);
+  if (!found) return undefined;
+
+  let source: string;
+  try {
+    source = await fs.readFile(path.join(workspaceRoot, baseDir, found), "utf-8");
+  } catch {
+    return undefined;
+  }
+  const parsed = parseFrontmatter(source);
+  return {
+    id: docId.toUpperCase(),
+    kind,
+    file: path.join(baseDir, found),
+    frontmatter: parsed.frontmatter,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// RFC stage derivation — shared by rfc.pipeline.status and queue.validate
+// ---------------------------------------------------------------------------
+
+export interface RfcStageInput {
+  status: string;
+  enhancedAt?: string;
+  implementedAt?: string;
+  auditFile?: string;
+  planFile?: string;
+}
+
+/** Compute the four pipeline stages for an RFC from frontmatter + artifacts. */
+export function computeRfcPipelineStages(input: RfcStageInput): RfcPipelineStageInfo[] {
+  return [
+    { stage: "audit", done: !!input.auditFile, evidence: input.auditFile },
+    {
+      stage: "enhance",
+      done: !!input.enhancedAt,
+      evidence: input.enhancedAt ? `enhancedAt: ${input.enhancedAt}` : undefined,
+    },
+    { stage: "plan", done: !!input.planFile, evidence: input.planFile },
+    {
+      stage: "implement",
+      done: input.status === "implemented" || !!input.implementedAt,
+      evidence: input.implementedAt ? `implementedAt: ${input.implementedAt}` : undefined,
+    },
+  ];
+}
+
+/** First incomplete stage for a non-terminal RFC, or null when terminal. */
+export function nextPipelineStep(
+  status: string,
+  stages: RfcPipelineStageInfo[],
+): PipelineStage | null {
+  if (TERMINAL_STATUSES.has(status)) return null;
+  for (const s of stages) {
+    if (!s.done) return s.stage;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Queue item derivation (RFC-1140)
+// ---------------------------------------------------------------------------
+
+export type QueueItemStatus = "pending" | "in-progress" | "implemented" | "skipped";
+
+export interface QueueItemReport {
+  id: string;
+  status: QueueItemStatus;
+  /** First incomplete pipeline stage — present only when in-progress. */
+  pipelineStep?: PipelineStage;
+}
+
+/**
+ * Derive the queue status of a single document per the RFC-1140 matrix:
+ * implemented → implemented; rejected/superseded → skipped; RFC accepted or
+ * plan file → in-progress/implement; enhancedAt → in-progress/plan; audit
+ * file → in-progress/enhance; otherwise pending. ADR non-terminal → pending.
+ */
+export async function deriveQueueItemStatus(
+  workspaceRoot: string,
+  docId: string,
+): Promise<QueueItemReport | undefined> {
+  const doc = await resolveDocument(workspaceRoot, docId);
+  if (!doc) return undefined;
+
+  const fm = doc.frontmatter;
+  const status = String(fm["status"] ?? "");
+  const implementedAt = fm["implementedAt"] ? String(fm["implementedAt"]) : undefined;
+
+  if (status === "implemented" || implementedAt) {
+    return { id: doc.id, status: "implemented" };
+  }
+  if (status === "rejected" || status === "superseded") {
+    return { id: doc.id, status: "skipped" };
+  }
+
+  // ADR pipeline is create → implement — no intermediate artifacts exist.
+  if (doc.kind === "adr") {
+    return { id: doc.id, status: "pending" };
+  }
+
+  // RFC accepted means the plan step is done by definition.
+  if (status === "accepted") {
+    return { id: doc.id, status: "in-progress", pipelineStep: "implement" };
+  }
+
+  const enhancedAt = fm["enhancedAt"] ? String(fm["enhancedAt"]) : undefined;
+  const auditFile = await findAuditFile(workspaceRoot, doc.id);
+  const planFile = await findPlanFile(workspaceRoot, doc.id);
+
+  const stages = computeRfcPipelineStages({
+    status,
+    enhancedAt,
+    implementedAt,
+    auditFile,
+    planFile,
+  });
+
+  // Queue semantics: the actionable step is the stage AFTER the last completed
+  // one — artifacts may be non-contiguous (e.g. enhancedAt without an audit
+  // file), where "first incomplete stage" would wrongly report audit.
+  let lastDone = -1;
+  for (let i = 0; i < stages.length; i++) {
+    if (stages[i]!.done) lastDone = i;
+  }
+  if (lastDone === -1) {
+    return { id: doc.id, status: "pending" };
+  }
+  const nextStage = stages[lastDone + 1];
+  if (!nextStage) {
+    return { id: doc.id, status: "pending" };
+  }
+  return { id: doc.id, status: "in-progress", pipelineStep: nextStage.stage };
+}
+
+export interface QueueReport {
+  items: QueueItemReport[];
+  /** First item whose derived status is pending or in-progress; null when fully terminal. */
+  next: string | null;
+}
+
+/** Derive the full queue report, preserving manifest order. */
+export async function deriveQueueReport(
+  workspaceRoot: string,
+  itemIds: string[],
+): Promise<QueueReport> {
+  const items: QueueItemReport[] = [];
+  for (const id of itemIds) {
+    const report = await deriveQueueItemStatus(workspaceRoot, id);
+    // Unresolvable ids are reported by the manifest validator; the resolver
+    // skips them here so a partial report stays usable.
+    if (report) items.push(report);
+  }
+  const nextItem = items.find((i) => i.status === "pending" || i.status === "in-progress");
+  return { items, next: nextItem?.id ?? null };
+}

package/src/tests/upgrade.test.ts

@@ -431,3 +431,56 @@ test("forge.upgrade without --update-npm does not attempt npm install", async ()
   expect(result.data?.npmUpdated).toBe(false);
   expect(result.data?.npmUpdateSkipped).toBe(null);
 });
+
+function qaLog(entries: { id: string; title: string; body: string }[]): string {
+  const blocks = entries.map(
+    (e) =>
+      `### ${e.id}: ${e.title}\n\n\`\`\`knowledge-entry\nid: ${e.id}\nlayer: L0\ncreated: 2026-08-03\nstatus: active\n\`\`\`\n\n${e.body}\n`,
+  );
+  return `<!-- knowledge-layer: L0 -->\n\n# Q&A Log (L0)\n\n${blocks.join("\n")}`;
+}
+
+test("forge.upgrade preserves project-accumulated knowledge entries (append-only merge)", async () => {
+  await setupForgeSource(tempDir, "0.2.0");
+  // Declare a knowledge file on the fixture skill
+  await writeFile(
+    join(tempDir, "packages", "forge", "skills", "fo", "fo-idea", "SKILL.md"),
+    "---\nname: fo-idea\nknowledge: [qa-log.md]\n---\n# fo-idea\n",
+    "utf8",
+  );
+  // Package ships K-0001 + new K-0003
+  await writeFile(
+    join(tempDir, "packages", "forge", "skills", "fo", "fo-idea", "qa-log.md"),
+    qaLog([
+      { id: "K-0001", title: "First", body: "Package body." },
+      { id: "K-0003", title: "Third", body: "New package entry." },
+    ]),
+    "utf8",
+  );
+  await setupConsumerForgeYaml(tempDir, null);
+
+  // Local copy already accumulated: edited K-0001 + project-only K-0002
+  await mkdir(join(tempDir, ".agents", "skills", "fo-idea"), { recursive: true });
+  await writeFile(
+    join(tempDir, ".agents", "skills", "fo-idea", "qa-log.md"),
+    qaLog([
+      { id: "K-0001", title: "First", body: "Locally edited body." },
+      { id: "K-0002", title: "Local record", body: "Project-accumulated entry." },
+    ]),
+    "utf8",
+  );
+
+  const result = await runUpgrade({ argv: [], flags: {} }, makeContext(tempDir, false));
+
+  expect(result.data?.status).toBe("pass");
+  const merged = await readFile(join(tempDir, ".agents", "skills", "fo-idea", "qa-log.md"), "utf8");
+  // Local entries preserved — the data-loss bug would have wiped K-0002
+  expect(merged).toContain("K-0002");
+  expect(merged).toContain("Project-accumulated entry.");
+  // Local version of the conflicting entry wins
+  expect(merged).toContain("Locally edited body.");
+  expect(merged).not.toContain("Package body.");
+  // New package entry appended
+  expect(merged).toContain("K-0003");
+  expect(merged).toContain("New package entry.");
+});

package/src/types.ts

@@ -16,6 +16,7 @@ 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>
+  <item>RFC-1147: ForgeRegisteredCommandInfo.provider narrowed to "workspace" and siteName field removed — forge never enumerated sites; mirrors the KernelRegisteredCommandInfo cleanup.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -112,8 +113,7 @@ export interface GateMetadata {
 
 export interface ForgeRegisteredCommandInfo extends ForgeCommandMetadata {
   name: string;
-  provider: "workspace" | "site";
-  siteName?: string;
+  provider: "workspace";
   module?: string;
   flags?: Record<string, ForgeFlagSpec>;
   reads?: string[];

package/src/utils/fs-atomic.ts

@@ -56,7 +56,7 @@ function sleep(ms: number): Promise<void> {
 function makeTempPath(filePath: string): string {
   const dir = dirname(filePath);
   const name = basename(filePath);
-  const random = randomBytes(6).toString("hex");
+  const random = Array.from(randomBytes(6), (b) => b.toString(16).padStart(2, "0")).join("");
   return join(dir, `${name}.${random}.tmp`);
 }