@warpgogol/forge 5.3.4 → 6.2.0

package/os/spec/spec-materialize.ts

@@ -8,6 +8,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0396: initial spec.materialize handler — front computation, scaffold via rfc.create, materializedAs write-back.</item>
+  <item>RFC-1240: consumer-aware front — consumers ownership gate, foreign-dep satisfaction, foreignOwned result field, --consumer flag resolution.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -29,6 +30,9 @@ import {
   type ForgeSpec,
   type SpecRfcNode,
   type SpecAmendment,
+  ownsSpecNode,
+  isForeignOwnedNode,
+  isForeignConsumerDep,
   resolveAmendedNode,
 } from "./spec-schema.ts";
 import { listRfcFiles } from "../rfc/frontmatter-io.ts";
@@ -55,6 +59,8 @@ interface SpecMaterializeResult {
   created: MaterializedNode[];
   skipped: SkippedNode[];
   front: string[];
+  /** RFC-1240: nodes excluded from the front by consumer ownership. */
+  foreignOwned: string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -94,6 +100,7 @@ export async function runSpecMaterialize(
         created: [],
         skipped: [],
         front: [],
+        foreignOwned: [],
       },
       exitCode: 1,
       summary: "spec.materialize: --spec=<id> is required",
@@ -101,12 +108,16 @@ export async function runSpecMaterialize(
   }
 
   let specsDir = "docs/specs";
+  let configConsumer: string | undefined;
   try {
     const config = loadForgeConfig(workspaceRoot);
     specsDir = config.paths.specsDir;
+    configConsumer = config.project.consumer;
   } catch {
     // Use default
   }
+  // RFC-1240: --consumer flag wins; otherwise forge.yaml project.consumer; else no identity.
+  const localConsumer = (input.flags["consumer"] as string | undefined) ?? configConsumer;
 
   const specDir = path.join(workspaceRoot, specsDir, specId);
   const forgeSpecPath = path.join(specDir, "forge-spec.yaml");
@@ -120,6 +131,7 @@ export async function runSpecMaterialize(
         created: [],
         skipped: [],
         front: [],
+        foreignOwned: [],
       },
       exitCode: 1,
       summary: `spec.materialize: forge-spec.yaml not found for spec '${specId}'`,
@@ -136,6 +148,7 @@ export async function runSpecMaterialize(
         created: [],
         skipped: [],
         front: [],
+        foreignOwned: [],
       },
       exitCode: 1,
       summary: `spec.materialize: forge-spec.yaml schema violation for spec '${specId}'`,
@@ -153,6 +166,7 @@ export async function runSpecMaterialize(
         created: [],
         skipped: [],
         front: [],
+        foreignOwned: [],
       },
       exitCode: 1,
       summary: `spec.materialize: spec '${specId}' is not accepted (status: ${spec.status}). Run /fo-spec-ingest to complete acceptance.`,
@@ -220,10 +234,27 @@ export async function runSpecMaterialize(
     }
   }
 
-  // Compute front: unmaterialized nodes whose deps are all implemented
+  // RFC-1240: consumer ownership — a node with `consumers` is ours only when the
+  // resolved local consumer identity is a member. Without local identity every
+  // consumer-declared node is treated as not locally owned.
+  const nodeById = new Map(spec.rfcs.map((n) => [n.id, n]));
+  const ownsNode = (node: SpecRfcNode): boolean =>
+    ownsSpecNode(node, localConsumer);
+  const depSatisfied = (depId: string): boolean => {
+    if (nodeState.get(depId) === "implemented") return true;
+    // Foreign-consumer dependency: an implementation duty of another consumer.
+    return isForeignConsumerDep(nodeById.get(depId), localConsumer);
+  };
+  const foreignOwned = spec.rfcs
+    .filter((n) => isForeignOwnedNode(n, localConsumer))
+    .map((n) => n.id);
+
+  // Compute front: unmaterialized, locally-owned nodes whose deps are all
+  // implemented or foreign-owned (RFC-1240).
   function isFront(node: SpecRfcNode): boolean {
     if (node.materializedAs) return false;
-    return node.dependsOn.every((dep) => nodeState.get(dep) === "implemented");
+    if (!ownsNode(node)) return false;
+    return node.dependsOn.every(depSatisfied);
   }
 
   const frontNodes = spec.rfcs.filter(isFront);
@@ -241,8 +272,15 @@ export async function runSpecMaterialize(
       if (!node) {
         skipped.push({ node: nodeId, reason: "node not found in spec" });
       } else if (!isFront(node)) {
-        const blockers = node.dependsOn.filter((d) => nodeState.get(d) !== "implemented");
-        skipped.push({ node: nodeId, reason: `blocked by ${blockers.join(", ")}` });
+        if (!ownsSpecNode(node, localConsumer)) {
+          const reason = localConsumer == null
+            ? "consumer identity not configured"
+            : `foreign-owned by ${(node.consumers ?? []).join(", ")}`;
+          skipped.push({ node: nodeId, reason });
+        } else {
+          const blockers = node.dependsOn.filter((d) => !depSatisfied(d));
+          skipped.push({ node: nodeId, reason: `blocked by ${blockers.join(", ")}` });
+        }
       } else {
         toMaterialize.push(node);
       }
@@ -256,6 +294,7 @@ export async function runSpecMaterialize(
           created: [],
           skipped,
           front: frontNodes.map((n) => n.id),
+          foreignOwned,
         },
         exitCode: 1,
         summary: `spec.materialize: all requested nodes blocked or not found`,
@@ -293,6 +332,7 @@ export async function runSpecMaterialize(
         created: [],
         skipped: [],
         front: frontNodes.map((n) => n.id),
+        foreignOwned,
       },
       exitCode: 1,
       summary: `spec.materialize: RFC template not found at ${templatePath}`,
@@ -373,6 +413,9 @@ export async function runSpecMaterialize(
     if (remainingFront.length > 0) {
       logger.info(`Remaining front: ${remainingFront.join(", ")}`);
     }
+    if (foreignOwned.length > 0) {
+      logger.info(`Foreign-owned nodes (excluded from front): ${foreignOwned.join(", ")}`);
+    }
   }
 
   return {
@@ -383,6 +426,7 @@ export async function runSpecMaterialize(
       created,
       skipped,
       front: remainingFront,
+      foreignOwned,
     },
     exitCode: 0,
     summary: `spec.materialize: created ${created.length} RFC(s) from spec '${specId}'`,

package/os/spec/spec-schema.ts

@@ -8,6 +8,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0394: initial spec schema — forge/spec@1, integrity manifest, decision/rfc/wave types.</item>
+  <item>RFC-1240: consumers field on roadmap nodes (consumer ownership filtering); severity field on SpecViolation for warning diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -38,6 +39,8 @@ export const specRfcNodeSchema = z.object({
   wave: z.number().int().min(1),
   sources: z.array(z.string()).default([]),
   materializedAs: z.string().optional(),
+  /** RFC-1240: consumer ownership — absent means the node materializes everywhere. */
+  consumers: z.array(z.string().min(1)).optional(),
 });
 
 export type SpecRfcNode = z.infer<typeof specRfcNodeSchema>;
@@ -77,6 +80,50 @@ export const forgeSpecSchema = z.object({
 
 export type ForgeSpec = z.infer<typeof forgeSpecSchema>;
 
+// ---------------------------------------------------------------------------
+// Consumer ownership predicates (RFC-1240)
+// ---------------------------------------------------------------------------
+
+/**
+ * True when the node may materialize for this workspace's consumer identity.
+ * A node without `consumers` is owned by every consumer.
+ */
+export function ownsSpecNode(
+  node: SpecRfcNode,
+  localConsumer: string | undefined,
+): boolean {
+  return (
+    !node.consumers ||
+    (localConsumer != null && node.consumers.includes(localConsumer))
+  );
+}
+
+/**
+ * True when the node declares `consumers` but is not locally owned —
+ * either the local identity is absent or it is not a member.
+ */
+export function isForeignOwnedNode(
+  node: SpecRfcNode,
+  localConsumer: string | undefined,
+): boolean {
+  return node.consumers != null && !ownsSpecNode(node, localConsumer);
+}
+
+/**
+ * True when a dependency node's implementation duty belongs to other
+ * consumers — it satisfies dependents without a local implementation.
+ */
+export function isForeignConsumerDep(
+  depNode: SpecRfcNode | undefined,
+  localConsumer: string | undefined,
+): boolean {
+  return (
+    depNode?.consumers != null &&
+    localConsumer != null &&
+    !depNode.consumers.includes(localConsumer)
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Integrity manifest (forge/spec-integrity@1)
 // ---------------------------------------------------------------------------
@@ -95,6 +142,8 @@ export type SpecIntegrity = z.infer<typeof specIntegritySchema>;
 export interface SpecViolation {
   rule: string;
   message: string;
+  /** RFC-1240: warnings (e.g. missing consumer identity) do not fail validation. */
+  severity?: "error" | "warning";
 }
 
 export interface SpecValidateResult {

package/os/spec/spec-status.ts

@@ -7,6 +7,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0396: initial spec.status handler — per-node states, blockers, front, progress.</item>
+  <item>RFC-1240: consumer-aware front — foreignOwned flag/list, foreign deps are not local blockers, --consumer flag resolution.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -23,6 +24,8 @@ import type {
 import {
   forgeSpecSchema,
   specAmendmentSchema,
+  isForeignConsumerDep,
+  isForeignOwnedNode,
   type ForgeSpec,
   type SpecAmendment,
 } from "./spec-schema.ts";
@@ -37,6 +40,8 @@ interface SpecNodeStatus {
   materializedAs?: string;
   wave: number;
   blockedBy: string[];
+  /** RFC-1240: true when the node is owned by other consumers (excluded from front). */
+  foreignOwned: boolean;
 }
 
 interface SpecProgress {
@@ -49,6 +54,8 @@ interface SpecStatusEntry {
   status: string;
   nodes: SpecNodeStatus[];
   front: string[];
+  /** RFC-1240: nodes excluded from the front by consumer ownership. */
+  foreignOwned: string[];
   progress: SpecProgress;
   amendments?: {
     proposed: number;
@@ -138,6 +145,8 @@ function computeFront(
 ): string[] {
   return nodes
     .filter((n) => n.state === "unmaterialized")
+    // RFC-1240: foreign-owned nodes are never on the local front.
+    .filter((n) => !n.foreignOwned)
     .filter((n) => n.blockedBy.every((dep) => {
       const depNode = nodeMap.get(dep);
       return depNode?.state === "implemented";
@@ -156,12 +165,16 @@ export async function runSpecStatus(
   const { workspaceRoot, logger, outputFormat } = context;
 
   let specsDir = "docs/specs";
+  let configConsumer: string | undefined;
   try {
     const config = loadForgeConfig(workspaceRoot);
     specsDir = config.paths.specsDir;
+    configConsumer = config.project.consumer;
   } catch {
     // Use default
   }
+  // RFC-1240: --consumer flag wins; otherwise forge.yaml project.consumer; else no identity.
+  const localConsumer = (input.flags["consumer"] as string | undefined) ?? configConsumer;
 
   const specsRoot = path.join(workspaceRoot, specsDir);
   const rfcDir = path.join(workspaceRoot, "docs", "rfcs");
@@ -198,9 +211,15 @@ export async function runSpecStatus(
         else state = "draft";
       }
 
+      // RFC-1240: a node with `consumers` not containing the local consumer
+      // identity (or any `consumers` when identity is absent) is foreign-owned.
+      const foreignOwned = isForeignOwnedNode(node, localConsumer);
+
       const blockedBy = node.dependsOn.filter((dep) => {
         const depNode = spec.rfcs.find((n) => n.id === dep);
         if (!depNode) return false;
+        // RFC-1240: a dependency owned by other consumers is not a local blocker.
+        if (isForeignConsumerDep(depNode, localConsumer)) return false;
         if (!depNode.materializedAs) return true;
         const depStatus = rfcStatuses.get(depNode.materializedAs);
         return depStatus !== "implemented";
@@ -212,6 +231,7 @@ export async function runSpecStatus(
         materializedAs: node.materializedAs,
         wave: node.wave,
         blockedBy,
+        foreignOwned,
       };
       nodes.push(nodeStatus);
       nodeMap.set(node.id, nodeStatus);
@@ -240,6 +260,7 @@ export async function runSpecStatus(
       status: spec.status,
       nodes,
       front,
+      foreignOwned: nodes.filter((n) => n.foreignOwned).map((n) => n.id),
       progress,
       amendments: {
         proposed: amendments.filter((a) => a.status === "proposed").length,
@@ -261,6 +282,9 @@ export async function runSpecStatus(
           `Progress: ${entry.progress.implemented}/${entry.progress.total} implemented`,
         );
         logger.info(`Front: ${entry.front.join(", ") || "(none)"}`);
+        if (entry.foreignOwned.length > 0) {
+          logger.info(`Foreign-owned: ${entry.foreignOwned.join(", ")}`);
+        }
         for (const node of entry.nodes) {
           const blocked = node.blockedBy.length > 0
             ? ` [blocked by ${node.blockedBy.join(", ")}]`

package/os/spec/spec-validate.test.ts

@@ -19,6 +19,72 @@ afterEach(async () => {
   await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));
 });
 
+describe("spec.validate consumer rules (RFC-1240)", () => {
+  async function writeConsumerSpec(workspaceRoot: string, consumersYaml: string): Promise<void> {
+    const specDir = path.join(workspaceRoot, "docs/specs/example");
+    await fs.mkdir(specDir, { recursive: true });
+    await fs.writeFile(path.join(specDir, "forge-spec.yaml"), `schema: forge/spec@1
+id: example
+title: Example
+version: 1.0.0
+status: accepted
+reviewers: []
+sourceNote: test fixture
+vendoredAt: 2026-10-09
+documents: {}
+decisions: []
+rfcs:
+  - id: EX-001
+    title: Consumer node
+    dependsOn: []
+    wave: 1
+    sources: []
+${consumersYaml}waves:
+  - id: 1
+    name: Test
+    goal: Exercise consumer rules
+`);
+    await fs.writeFile(path.join(specDir, "integrity.yaml"), "schema: forge/spec-integrity@1\nfiles: {}\n");
+  }
+
+  function ctx(workspaceRoot: string): ForgeRuntimeContext {
+    return { workspaceRoot, dryRun: false, outputFormat: "json",
+      logger: { section() {}, info() {}, warn() {}, error() {}, success() {} } } as ForgeRuntimeContext;
+  }
+
+  it("emits SPEC-13 warning without failing when consumers exist but no local identity is configured", async () => {
+    const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "spec-validate-consumer-"));
+    roots.push(workspaceRoot);
+    await writeConsumerSpec(workspaceRoot, "    consumers:\n      - personal-agent\n");
+    const result = await runSpecValidate({ argv: [], flags: { spec: "example" } }, ctx(workspaceRoot));
+    expect(result.exitCode).toBe(0);
+    expect(result.data.status).toBe("pass");
+    const warnings = result.data.specs[0]!.violations.filter((v) => v.severity === "warning");
+    expect(warnings.map((v) => v.rule)).toEqual(["SPEC-13"]);
+    expect(warnings[0]!.message).toContain("EX-001");
+  });
+
+  it("does not emit SPEC-13 when project.consumer is configured", async () => {
+    const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "spec-validate-consumer-"));
+    roots.push(workspaceRoot);
+    await fs.writeFile(path.join(workspaceRoot, "forge.yaml"),
+      "schema: forge/config@1\nproject:\n  name: test-ws\n  consumer: werkstatt\npaths: {}\n");
+    await writeConsumerSpec(workspaceRoot, "    consumers:\n      - personal-agent\n");
+    const result = await runSpecValidate({ argv: [], flags: { spec: "example" } }, ctx(workspaceRoot));
+    expect(result.exitCode).toBe(0);
+    expect(result.data.specs[0]!.violations).toEqual([]);
+  });
+
+  it("fails with SPEC-12 on duplicate consumer entries", async () => {
+    const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "spec-validate-consumer-"));
+    roots.push(workspaceRoot);
+    await writeConsumerSpec(workspaceRoot, "    consumers:\n      - werkstatt\n      - werkstatt\n");
+    const result = await runSpecValidate({ argv: [], flags: { spec: "example" } }, ctx(workspaceRoot));
+    expect(result.exitCode).toBe(1);
+    expect(result.data.specs[0]!.violations.map((v) => v.rule)).toContain("SPEC-12");
+  });
+});
+
 describe("spec.validate SPEC-07", () => {
   it("accepts a materialized RFC after docs.archive moves it below archive/implemented", async () => {
     const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "spec-validate-archive-"));

package/os/spec/spec-validate.ts

@@ -10,6 +10,7 @@
 <CHANGE_SUMMARY>
   <item>RFC-0394: initial spec.validate handler with SPEC-01..07 rules.</item>
   <item>Gap fix: resolve materialized RFCs recursively so terminal RFC archival does not invalidate accepted specs.</item>
+  <item>RFC-1240: SPEC-12 consumers list hygiene, SPEC-13 consumer-identity warning; warnings no longer fail validation.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -280,6 +281,45 @@ async function checkMaterializedAs(
   }
 }
 
+// ---------------------------------------------------------------------------
+// SPEC-12: consumers list hygiene / SPEC-13: consumer identity configured (RFC-1240)
+// ---------------------------------------------------------------------------
+
+function checkConsumers(
+  spec: ForgeSpec,
+  localConsumer: string | undefined,
+  violations: SpecViolation[],
+): void {
+  const identityNodes: string[] = [];
+  for (const node of spec.rfcs) {
+    if (!node.consumers) continue;
+    if (node.consumers.length === 0) {
+      violations.push({
+        rule: "SPEC-12",
+        message: `node ${node.id} declares an empty consumers list`,
+      });
+    }
+    const seen = new Set<string>();
+    for (const consumer of node.consumers) {
+      if (seen.has(consumer)) {
+        violations.push({
+          rule: "SPEC-12",
+          message: `node ${node.id} declares duplicate consumer '${consumer}'`,
+        });
+      }
+      seen.add(consumer);
+    }
+    if (localConsumer == null) identityNodes.push(node.id);
+  }
+  if (identityNodes.length > 0) {
+    violations.push({
+      rule: "SPEC-13",
+      severity: "warning",
+      message: `consumer identity not configured — nodes declaring consumers cannot be owned locally: ${identityNodes.join(", ")} (set project.consumer in forge.yaml or pass --consumer)`,
+    });
+  }
+}
+
 // ---------------------------------------------------------------------------
 // SPEC-08..11: Amendment validation (RFC-0397)
 // ---------------------------------------------------------------------------
@@ -401,12 +441,16 @@ export async function runSpecValidate(
 
   // Resolve specs directory from forge.yaml
   let specsDir = "docs/specs";
+  let configConsumer: string | undefined;
   try {
     const config = loadForgeConfig(workspaceRoot);
     specsDir = config.paths.specsDir;
+    configConsumer = config.project.consumer;
   } catch {
     // Use default
   }
+  // RFC-1240: --consumer flag wins; otherwise forge.yaml project.consumer; else no identity.
+  const localConsumer = (input.flags["consumer"] as string | undefined) ?? configConsumer;
 
   const specsRoot = path.join(workspaceRoot, specsDir);
   const filterSpec = input.flags["spec"] as string | undefined;
@@ -475,6 +519,9 @@ export async function runSpecValidate(
     const amendments = await loadAmendments(specDir);
     checkAmendments(spec, amendments, violations);
 
+    // SPEC-12/13: consumers hygiene + identity warning (RFC-1240)
+    checkConsumers(spec, localConsumer, violations);
+
     results.push({
       id: spec.id,
       status: spec.status,
@@ -482,20 +529,27 @@ export async function runSpecValidate(
     });
   }
 
-  const hasFailures = results.some((r) => r.violations.length > 0);
+  const hasFailures = results.some((r) =>
+    r.violations.some((v) => v.severity !== "warning"),
+  );
 
   if (outputFormat === "pretty") {
     if (results.length === 0) {
       logger.info("No vendored specs found.");
     } else {
       for (const result of results) {
-        if (result.violations.length === 0) {
-          logger.success(`spec.validate: ${result.id} — pass`);
+        const errors = result.violations.filter((v) => v.severity !== "warning");
+        const warnings = result.violations.filter((v) => v.severity === "warning");
+        if (errors.length === 0) {
+          logger.success(`spec.validate: ${result.id} — pass${warnings.length > 0 ? ` (${warnings.length} warning${warnings.length === 1 ? "" : "s"})` : ""}`);
         } else {
-          logger.error(`spec.validate: ${result.id} — ${result.violations.length} violation${result.violations.length === 1 ? "" : "s"}`);
-          for (const v of result.violations) {
-            logger.error(`  ${v.rule}: ${v.message}`);
-          }
+          logger.error(`spec.validate: ${result.id} — ${errors.length} violation${errors.length === 1 ? "" : "s"}`);
+        }
+        for (const v of errors) {
+          logger.error(`  ${v.rule}: ${v.message}`);
+        }
+        for (const v of warnings) {
+          logger.warn(`  ${v.rule}: ${v.message}`);
         }
       }
     }
@@ -509,7 +563,7 @@ export async function runSpecValidate(
     },
     exitCode: hasFailures ? 1 : 0,
     summary: hasFailures
-      ? `spec.validate: ${results.filter((r) => r.violations.length > 0).length} spec(s) with violations`
+      ? `spec.validate: ${results.filter((r) => r.violations.some((v) => v.severity !== "warning")).length} spec(s) with violations`
       : `spec.validate: all ${results.length} spec(s) pass`,
   };
 }